funifier-mcp 0.3.20 → 0.3.22

package/.cursor/rules/funifier.mdc

@@ -62,6 +62,7 @@ Then read a result with `funifier_read_doc path=<path>`.
 | `skills/funifier/references/upload-file.md` | Upload files to Funifier — images and documents for player avatars, challenge resources, and visual assets; use when adding media to the platform, not for CSV data import (use funifier-import-csv) or static frontend hosting (use funifier-implement-frontend) |
 | `skills/funifier/references/manage-indexes.md` | Create, list, and drop MongoDB single-field indexes on Funifier collections via the REST API. Composite (multi-field) indexes are NOT supported by this endpoint — see Limitation section. |
 | `skills/funifier/references/audit-permissions.md` | Cross-check a project's Funifier API calls against the live security document — scan code for usage, build an evidence-backed manifest, run the deterministic audit engine, and report missing scopes, excess tokens, and static danger findings; use when debugging 401s, auditing minimum privilege, or verifying permissions before deploying; audit is read-only and never changes any configuration |
+| `skills/funifier/references/server-utils.md` | Use the server-side utility classes from com.funifier.engine.util in Groovy triggers, schedulers, and public endpoints — validates CPF, encrypts fields with AES/BCrypt/PGP, renders Mustache templates, evaluates inline expressions, computes object diffs/changelogs, converts JSON, generates Excel, makes HTTP calls, and handles files and pagination |
 
 Full workflow files: `skills/funifier/references/`
 

package/.github/copilot-instructions.md

@@ -55,6 +55,7 @@ Detailed guided workflows live in `skills/funifier/references/`:
 | `skills/funifier/references/upload-file.md` | Upload files to Funifier — images and documents for player avatars, challenge resources, and visual assets; use when adding media to the platform, not for CSV data import (use funifier-import-csv) or static frontend hosting (use funifier-implement-frontend) |
 | `skills/funifier/references/manage-indexes.md` | Create, list, and drop MongoDB single-field indexes on Funifier collections via the REST API. Composite (multi-field) indexes are NOT supported by this endpoint — see Limitation section. |
 | `skills/funifier/references/audit-permissions.md` | Cross-check a project's Funifier API calls against the live security document — scan code for usage, build an evidence-backed manifest, run the deterministic audit engine, and report missing scopes, excess tokens, and static danger findings; use when debugging 401s, auditing minimum privilege, or verifying permissions before deploying; audit is read-only and never changes any configuration |
+| `skills/funifier/references/server-utils.md` | Use the server-side utility classes from com.funifier.engine.util in Groovy triggers, schedulers, and public endpoints — validates CPF, encrypts fields with AES/BCrypt/PGP, renders Mustache templates, evaluates inline expressions, computes object diffs/changelogs, converts JSON, generates Excel, makes HTTP calls, and handles files and pagination |
 
 ### Funifier Modules
 

package/AGENTS.md

@@ -94,6 +94,7 @@ Before any `funifier_*` MCP tool call or Funifier task, find the matching row an
 | `skills/funifier/references/upload-file.md` | Upload files to Funifier — images and documents for player avatars, challenge resources, and visual assets; use when adding media to the platform, not for CSV data import (use funifier-import-csv) or static frontend hosting (use funifier-implement-frontend) |
 | `skills/funifier/references/manage-indexes.md` | Create, list, and drop MongoDB single-field indexes on Funifier collections via the REST API. Composite (multi-field) indexes are NOT supported by this endpoint — see Limitation section. |
 | `skills/funifier/references/audit-permissions.md` | Cross-check a project's Funifier API calls against the live security document — scan code for usage, build an evidence-backed manifest, run the deterministic audit engine, and report missing scopes, excess tokens, and static danger findings; use when debugging 401s, auditing minimum privilege, or verifying permissions before deploying; audit is read-only and never changes any configuration |
+| `skills/funifier/references/server-utils.md` | Use the server-side utility classes from com.funifier.engine.util in Groovy triggers, schedulers, and public endpoints — validates CPF, encrypts fields with AES/BCrypt/PGP, renders Mustache templates, evaluates inline expressions, computes object diffs/changelogs, converts JSON, generates Excel, makes HTTP calls, and handles files and pagination |
 
 ## Funifier Modules
 

package/CHANGELOG.md

@@ -3,6 +3,37 @@
 All notable changes to `funifier-mcp` are documented here. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com/); versions follow semver.
 
+## [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.
+
+### Documentation
+- **Add `guides/server-utils.md`.** Covers all 17 developer-facing classes in the Funifier server-side utilities package: `JsonUtil`, `StringUtil`, `CpfUtil`, `FormatterUtil`, `ParserUtil`, `ExpressionUtils`, `MustacheUtils`, `DiffUtil`, `AesCrypt`, `BCrypt`, `PgpCrypt`, `OtpAuthUtil`, `HttpUtil`, `UrlUtil`, `ExcelUtil`, `PaginationUtil`, and `FileUtil`. Each class has its FQN, real public signatures (verified against source), and ≥1 Groovy/Java server-side example. Security-sensitive classes (AesCrypt, BCrypt, PgpCrypt, OtpAuthUtil) include secret-management notes. `DateUtil` is cross-linked to `funifier-date-handling` instead of duplicated.
+- **Register in `knowledge/index.md`.** New entry in the Java guides section so the knowledge router surfaces the guide.
+
+### Skills
+- **New skill `funifier-server-utils`** in `scripts/skills-config.ts` + regenerated reference. Triggers on requests like "validar CPF", "criptografar campo", "gerar TOTP", "renderizar template Mustache", "diff de objeto", "converter JSON", "gerar Excel" and similar.
+
 ## [0.3.20]
 
 Documentation of trigger flow-interruption (strict mode) in the Funifier knowledge base.

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

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-06-22T14:54:00.000Z",
+  "generatedAt": "2026-07-01T15:34: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": [
@@ -39,7 +47,8 @@
       "status": "grouped",
       "skillIds": [
         "funifier-create-trigger",
-        "funifier-create-scheduler"
+        "funifier-create-scheduler",
+        "funifier-server-utils"
       ]
     },
     "knowledge/guides/permission-audit.md": {
@@ -48,6 +57,12 @@
         "funifier-audit-permissions"
       ]
     },
+    "knowledge/guides/server-utils.md": {
+      "status": "covered",
+      "skillIds": [
+        "funifier-server-utils"
+      ]
+    },
     "knowledge/guides/trigger-examples.md": {
       "status": "grouped",
       "skillIds": [
@@ -59,7 +74,8 @@
       "status": "grouped",
       "skillIds": [
         "funifier-create-trigger",
-        "funifier-debug"
+        "funifier-debug",
+        "funifier-server-utils"
       ]
     },
     "knowledge/index.md": {
@@ -338,9 +354,9 @@
     }
   },
   "summary": {
-    "total": 52,
-    "covered": 32,
-    "grouped": 14,
+    "total": 54,
+    "covered": 33,
+    "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).