funifier-mcp 0.3.17 → 0.3.19

package/.cursor/rules/funifier.mdc

@@ -27,7 +27,8 @@ Then read a result with `funifier_read_doc path=<path>`.
 |-----------|-------------|
 | `skills/funifier/references/create-trigger.md` | Create a Funifier trigger — guided workflow from entity/event selection to Groovy code generation |
 | `skills/funifier/references/create-scheduler.md` | Create a Funifier scheduler — guided workflow from naming and cron expression to Groovy code generation |
-| `skills/funifier/references/create-aggregate.md` | Create a Funifier prepared aggregate — guided workflow for building MongoDB aggregate pipelines for reports and dashboards |
+| `skills/funifier/references/query-aggregate.md` | Run an ad-hoc MongoDB aggregate (one-off query) on a Funifier collection via POST /v3/database/{collection}/aggregate — for reports and exploration, without saving a resource |
+| `skills/funifier/references/create-aggregate.md` | Create/edit a Funifier prepared aggregate — a saved pipeline with _id, $param placeholders, optional Groovy script, cache and execution via POST /v3/find/{id}; for reusable dashboards and parametrized reports |
 | `skills/funifier/references/date-handling.md` | Create, edit, or query Date fields safely via REST, funifier_database, triggers, schedulers, aggregate, and prepared aggregate; use whenever a payload or filter contains dates |
 | `skills/funifier/references/create-challenge.md` | Create a Funifier challenge — missions with action rules and point rewards |
 | `skills/funifier/references/create-action.md` | Create a Funifier action — define trackable player behaviors with attributes |
@@ -60,6 +61,7 @@ Then read a result with `funifier_read_doc path=<path>`.
 | `skills/funifier/references/import-csv.md` | Import or export Funifier platform data via CSV — bulk player import, performance export, and cross-system data migration; use when loading or extracting large datasets, not for individual record CRUD or media file uploads (use funifier-upload-file) |
 | `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 |
 
 Full workflow files: `skills/funifier/references/`
 

package/.github/copilot-instructions.md

@@ -20,7 +20,8 @@ Detailed guided workflows live in `skills/funifier/references/`:
 |-----------|-------------|
 | `skills/funifier/references/create-trigger.md` | Create a Funifier trigger — guided workflow from entity/event selection to Groovy code generation |
 | `skills/funifier/references/create-scheduler.md` | Create a Funifier scheduler — guided workflow from naming and cron expression to Groovy code generation |
-| `skills/funifier/references/create-aggregate.md` | Create a Funifier prepared aggregate — guided workflow for building MongoDB aggregate pipelines for reports and dashboards |
+| `skills/funifier/references/query-aggregate.md` | Run an ad-hoc MongoDB aggregate (one-off query) on a Funifier collection via POST /v3/database/{collection}/aggregate — for reports and exploration, without saving a resource |
+| `skills/funifier/references/create-aggregate.md` | Create/edit a Funifier prepared aggregate — a saved pipeline with _id, $param placeholders, optional Groovy script, cache and execution via POST /v3/find/{id}; for reusable dashboards and parametrized reports |
 | `skills/funifier/references/date-handling.md` | Create, edit, or query Date fields safely via REST, funifier_database, triggers, schedulers, aggregate, and prepared aggregate; use whenever a payload or filter contains dates |
 | `skills/funifier/references/create-challenge.md` | Create a Funifier challenge — missions with action rules and point rewards |
 | `skills/funifier/references/create-action.md` | Create a Funifier action — define trackable player behaviors with attributes |
@@ -53,6 +54,7 @@ Detailed guided workflows live in `skills/funifier/references/`:
 | `skills/funifier/references/import-csv.md` | Import or export Funifier platform data via CSV — bulk player import, performance export, and cross-system data migration; use when loading or extracting large datasets, not for individual record CRUD or media file uploads (use funifier-upload-file) |
 | `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 |
 
 ### Funifier Modules
 

package/AGENTS.md

@@ -59,7 +59,8 @@ Before any `funifier_*` MCP tool call or Funifier task, find the matching row an
 |-----------|-------------|
 | `skills/funifier/references/create-trigger.md` | Create a Funifier trigger — guided workflow from entity/event selection to Groovy code generation |
 | `skills/funifier/references/create-scheduler.md` | Create a Funifier scheduler — guided workflow from naming and cron expression to Groovy code generation |
-| `skills/funifier/references/create-aggregate.md` | Create a Funifier prepared aggregate — guided workflow for building MongoDB aggregate pipelines for reports and dashboards |
+| `skills/funifier/references/query-aggregate.md` | Run an ad-hoc MongoDB aggregate (one-off query) on a Funifier collection via POST /v3/database/{collection}/aggregate — for reports and exploration, without saving a resource |
+| `skills/funifier/references/create-aggregate.md` | Create/edit a Funifier prepared aggregate — a saved pipeline with _id, $param placeholders, optional Groovy script, cache and execution via POST /v3/find/{id}; for reusable dashboards and parametrized reports |
 | `skills/funifier/references/date-handling.md` | Create, edit, or query Date fields safely via REST, funifier_database, triggers, schedulers, aggregate, and prepared aggregate; use whenever a payload or filter contains dates |
 | `skills/funifier/references/create-challenge.md` | Create a Funifier challenge — missions with action rules and point rewards |
 | `skills/funifier/references/create-action.md` | Create a Funifier action — define trackable player behaviors with attributes |
@@ -92,6 +93,7 @@ Before any `funifier_*` MCP tool call or Funifier task, find the matching row an
 | `skills/funifier/references/import-csv.md` | Import or export Funifier platform data via CSV — bulk player import, performance export, and cross-system data migration; use when loading or extracting large datasets, not for individual record CRUD or media file uploads (use funifier-upload-file) |
 | `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 |
 
 ## Funifier Modules
 

package/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable changes to `funifier-mcp` are documented here. Format loosely follows
+[Keep a Changelog](https://keepachangelog.com/); versions follow semver.
+
+## [0.3.19]
+
+Implementation of the prioritized improvements from the MCP implementation review
+(`.specs/features/mcp-implementation-review/review-report.md`).
+
+### Security
+- **Stop leaking credentials in logs (P0/S1).** API errors are now logged through a
+  sanitizer that emits only the message + status; the raw axios error (which carries
+  `Authorization: Basic …` and the request body) is never written to stderr.
+- **Close path traversal in the docs resource (P0/S2).** `funifier://docs/{+path}` now
+  shares the same root-confinement guard as `funifier_read_doc` via `src/mcp/doc-path.ts`,
+  blocking `../` escapes.
+- **Restrict file permissions (P1/S3).** `funifier.json` and backup snapshots are written
+  with mode `0600` and the backup directory with `0700` (both hold plaintext secrets).
+- **Mark untrusted API data (P2/S6).** `funifier_database` query/aggregate and
+  `funifier_logs` responses are prefixed with a delimiter telling the agent to treat
+  end-user-influenced data as data, never as instructions.
+
+### Reliability
+- **Request timeout + retry (P0/P3).** The axios client now aborts after 30s and retries
+  idempotent GETs (network error / timeout / 5xx) with exponential backoff.
+- **Graceful shutdown (P2/M1).** The server closes the transport on `SIGTERM`/`SIGINT`.
+
+### Performance / token usage
+- **Aggregate result cap (P1).** Ad-hoc aggregate pipelines without an explicit `$limit`
+  get a `$limit:1000` backstop, and prepared-aggregate `run` results pass through the
+  response size guard.
+
+### Maintainability
+- **Resource-type registry (P1/A1).** `src/mcp/tools/_registry.ts` is now the single
+  source of truth mapping each resource type to its api-client methods and tool exposure,
+  replacing the duplicated switch/dispatch blocks in `save`/`delete`/`get`/`list`/
+  `_fetch-current`. A consistency test freezes per-tool membership and verifies every
+  registered method exists on the client.
+- **Structured logging (P1/O1).** A minimal JSON-lines stderr logger (`src/core/logger.ts`)
+  records one line per tool call (tool, duration, outcome) and the reason whenever a list
+  call returns `[]` due to an error.
+
+### Update notifications
+- The in-session update notice now links to this changelog, and scales its tone with
+  severity: routine patch/minor updates get a quiet one-liner, while major bumps
+  (including pre-1.0 minor bumps, per semver convention) warn about breaking changes
+  and tell the user to review the changelog before updating.
+
+### Tests
+- Added coverage for the doc-path guard, retry policy, aggregate cap, resource registry
+  dispatch/consistency, `ApiHolder`, and severity-aware update notices. Suite: 471 tests passing.
+
+### Deferred (documented, not changed)
+- Replacing the global `Range: items=0-1000` header with per-call pagination on the
+  generic list tool (platform-wide behavior change — needs a deliberate decision).
+- True GET-by-id in `fetchCurrentById` (most Funifier resources expose only list endpoints).
+- Automatic backup retention/expiry (auto-deleting snapshots is destructive; left manual).
+- Server-side aggregate stage denylist (`$out`/`$merge`) — pending confirmation of backend behavior.

package/README.md

@@ -7,7 +7,7 @@ Funifier AI toolkit — API client, MCP server, and AI assistant skills for the
 | Component | Description |
 |-----------|-------------|
 | **API Client** | Pure Node.js client for the Funifier REST API (80+ methods, 18 resource types) |
-| **MCP Server** | Model Context Protocol server — 11 tools, 3 prompts, documentation resources |
+| **MCP Server** | Model Context Protocol server — 14 tools, 3 prompts, documentation resources |
 | **Skills** | 32 guided workflows for Claude Code, Codex, OpenCode, Copilot, Continue, and Cursor |
 | **CLI** | `npx funifier-mcp@latest init` — interactive setup for AI platforms |
 

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

@@ -1,10 +1,11 @@
 {
-  "generatedAt": "2026-06-12T12:49:00.000Z",
+  "generatedAt": "2026-06-12T18:58:00.000Z",
   "docsRoot": "datasource-funifier-docs/",
   "docs": {
     "knowledge/guides/aggregates.md": {
       "status": "grouped",
       "skillIds": [
+        "funifier-query-aggregate",
         "funifier-create-aggregate",
         "funifier-date-handling",
         "funifier-create-custom-page",
@@ -15,6 +16,7 @@
     "knowledge/guides/database-access.md": {
       "status": "grouped",
       "skillIds": [
+        "funifier-query-aggregate",
         "funifier-create-aggregate",
         "funifier-date-handling",
         "funifier-implement-frontend"
@@ -40,6 +42,12 @@
         "funifier-create-scheduler"
       ]
     },
+    "knowledge/guides/permission-audit.md": {
+      "status": "covered",
+      "skillIds": [
+        "funifier-audit-permissions"
+      ]
+    },
     "knowledge/guides/trigger-examples.md": {
       "status": "grouped",
       "skillIds": [
@@ -142,6 +150,7 @@
     "knowledge/modules/database.md": {
       "status": "grouped",
       "skillIds": [
+        "funifier-query-aggregate",
         "funifier-create-aggregate",
         "funifier-date-handling",
         "funifier-create-audit",
@@ -249,9 +258,10 @@
       ]
     },
     "knowledge/modules/security.md": {
-      "status": "covered",
+      "status": "grouped",
       "skillIds": [
-        "funifier-configure-security"
+        "funifier-configure-security",
+        "funifier-audit-permissions"
       ]
     },
     "knowledge/modules/staging.md": {
@@ -328,9 +338,9 @@
     }
   },
   "summary": {
-    "total": 51,
+    "total": 52,
     "covered": 32,
-    "grouped": 13,
+    "grouped": 14,
     "deferred": 6,
     "uncovered": 0
   }

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

@@ -1,13 +1,49 @@
 {
-  "generatedAt": "2026-06-12T12:18:00Z",
+  "generatedAt": "2026-06-12T17:50:00Z",
   "skills": {
+    "funifier-audit-permissions": {
+      "configHash": "f0569bdb0e11e1a2c6a11f6a4ff9cfd940668c7431bee06342b29faab32510fc",
+      "status": "verified",
+      "claims": [
+        {
+          "claim": "SecurityFilter.doFilter evaluates (method, path) by computing verb (GET→read, POST/PUT→write, DELETE→delete) and entity_full (path after /v3/ with slash→underscore), then matching scope tokens in order: {verb}_all, exact {verb}_{entity_full}, fallback {verb}_{prefix}_all minus-1 and minus-2 trailing segments",
+          "gitnexusQuery": "SecurityFilter",
+          "critical": true,
+          "status": "verified",
+          "evidence": {
+            "symbol": "Class:src/main/java/com/funifier/rest/v3/filter/SecurityFilter.java:SecurityFilter",
+            "file": "src/main/java/com/funifier/rest/v3/filter/SecurityFilter.java"
+          }
+        },
+        {
+          "claim": "DatabaseRest requires the literal 'database' scope keyword on ALL /v3/database handlers including GET operations — grammar tokens such as read_all alone are insufficient; this is enforced within SecurityFilter.doFilter before requests reach DatabaseRest handlers",
+          "gitnexusQuery": "doFilter",
+          "critical": true,
+          "status": "verified",
+          "evidence": {
+            "symbol": "Method:src/main/java/com/funifier/rest/v3/filter/SecurityFilter.java:SecurityFilter.doFilter#3",
+            "file": "src/main/java/com/funifier/rest/v3/filter/SecurityFilter.java"
+          }
+        },
+        {
+          "claim": "Bearer tokens embed the player's role scope string at login time; role scope changes only affect sessions created after the change — existing live Bearer tokens carry the scope at their issuance time",
+          "gitnexusQuery": "SecurityFilter",
+          "critical": true,
+          "status": "verified",
+          "evidence": {
+            "symbol": "Class:src/main/java/com/funifier/rest/v3/filter/SecurityFilter.java:SecurityFilter",
+            "file": "src/main/java/com/funifier/rest/v3/filter/SecurityFilter.java"
+          }
+        }
+      ]
+    },
     "funifier-configure-security": {
-      "configHash": "fba0f846a53838e369f5c079104cd4a2f16a9d535a0320701d16287e53f35496",
+      "configHash": "a05c3dc778b494d2d9d781787dd2231c1ae5720c3e368b41071f02df85a1a922",
       "status": "verified",
       "claims": []
     },
     "funifier-create-action": {
-      "configHash": "2b0f8eddb8f942fc407c1d19b15fdc80cb7d9a1e01c1093befdfd3c483c1cb68",
+      "configHash": "378dcd46c1dbad66e0363790d65d5bc0bba9ea3b294a97b571cc6d87c26ddf11",
       "status": "verified",
       "claims": [
         {
@@ -33,7 +69,7 @@
       ]
     },
     "funifier-create-aggregate": {
-      "configHash": "9598173385df039c369c8efc036ec22faaa3f9e56cb6c787498bf3d72b18a634",
+      "configHash": "c27031c7453134f3386ca29d55ab4d6ad25e20b0aec443d9cf84858f0984415f",
       "status": "verified",
       "claims": [
         {
@@ -49,7 +85,7 @@
       ]
     },
     "funifier-create-audit": {
-      "configHash": "17d53b67ecf952aaa352f0799e465d00de59960cd51cea31dee6f5d9ad5f5c8f",
+      "configHash": "0ca754be3545a16a6efb50ca2c4b360f1438efa1cd1bc2b5109aa76768376e07",
       "status": "verified",
       "claims": [
         {
@@ -85,7 +121,7 @@
       ]
     },
     "funifier-create-challenge": {
-      "configHash": "45e50eab442325d3342dddff5d7c48f34002fe0182ed78c31a48fffdb8eafd03",
+      "configHash": "7065294da9c53a9d1bbe544749ff552d6674d0d77e2534ea17e43fae4c72474c",
       "status": "verified",
       "claims": [
         {
@@ -111,7 +147,7 @@
       ]
     },
     "funifier-create-competition": {
-      "configHash": "ed7fe6dc128ebe0cbb417544d2f25209cf472a11fd38e4b78bb33b7662e54618",
+      "configHash": "0de8bcda95d0a1764ef4ce7aa7e78c53c7f7d492012534ecaf7f87600c42f078",
       "status": "verified",
       "claims": [
         {
@@ -137,7 +173,7 @@
       ]
     },
     "funifier-create-crossword": {
-      "configHash": "c1e731de20525b88b05c1f644c196fa5aa31c593a75f7f03de8c8030564ab5fb",
+      "configHash": "63ebc6f1e0589aaa748464e54b3dc3460094fa41764922534b6017288fc79541",
       "status": "verified",
       "claims": [
         {
@@ -153,7 +189,7 @@
       ]
     },
     "funifier-create-custom-object": {
-      "configHash": "58677f7f00c4d432e792f825bbc12b11e61722057c143d4a291da600d5beb758",
+      "configHash": "8aa7a96fdc72793c3d095db04831396d58a1aca931a7542cc8d5b8eed2e0c31d",
       "status": "verified",
       "claims": [
         {
@@ -169,7 +205,7 @@
       ]
     },
     "funifier-create-custom-page": {
-      "configHash": "d7a517d522858c659e5ead012c9f0594829aee22d96cda561536fbb803cd5db0",
+      "configHash": "0645081a8fd47315f92446ecaf7f8c55837b5e87c1339aad1ea9eb63c6cd7a18",
       "status": "verified",
       "claims": [
         {
@@ -185,7 +221,7 @@
       ]
     },
     "funifier-create-folder": {
-      "configHash": "ec7b1e3fadcd07d89f271f1bc10a28f820916fe8c0e645da88d48a43db868966",
+      "configHash": "16b0c0ae4ddebd51a16a0f330a80bed8c186cd7a760a9e52a5fb16d3cf6e462f",
       "status": "verified",
       "claims": [
         {
@@ -211,7 +247,7 @@
       ]
     },
     "funifier-create-lastmile": {
-      "configHash": "176113c689332843b24d22f7705d1361dfabf3e369de816b59b33a86ed0d9041",
+      "configHash": "e769c3ad773a9069ae41902d52195b81cfaaf6eb61cc15fb1d443c95ae512e55",
       "status": "verified",
       "claims": [
         {
@@ -227,7 +263,7 @@
       ]
     },
     "funifier-create-leaderboard": {
-      "configHash": "1cd6bca4e73fda88a8a4e965af46f45acbba2508098557f321819fbe04d57fb3",
+      "configHash": "f0baaf27834eb5f75c75ba1ddb0054e72a1cf88a52d685601acd4781fafec025",
       "status": "verified",
       "claims": [
         {
@@ -243,7 +279,7 @@
       ]
     },
     "funifier-create-level": {
-      "configHash": "c50ed12fceedfc2288bd2006f743528f440ab57de9f8321ae0297f0eb6199eae",
+      "configHash": "807c32381d542e5e1bbd678b29bc79751af340b7e00a31264a1dd24839306dab",
       "status": "verified",
       "claims": [
         {
@@ -269,7 +305,7 @@
       ]
     },
     "funifier-create-lottery": {
-      "configHash": "073bed793dd691ac19d095fa52839f4129532b7ff49eef4e35e9c84954d1b540",
+      "configHash": "ba9945f649f2e2fe91d545d27131b0e705b729deba192d121b8e41a03e3d5078",
       "status": "verified",
       "claims": [
         {
@@ -295,7 +331,7 @@
       ]
     },
     "funifier-create-mystery": {
-      "configHash": "ab423bcca3614806f63a3366db19629fe3127dc2989975f181cb0171be37d312",
+      "configHash": "0251df7c50e9629c592abef26894cc4b37d2a00c32ce6021c47eeedad3df35bb",
       "status": "verified",
       "claims": [
         {
@@ -311,7 +347,7 @@
       ]
     },
     "funifier-create-notification": {
-      "configHash": "1fd4dbbc94ba9aa72ae464b4c2c40b23f612e8b7c49fae7a8f1136950c0474a2",
+      "configHash": "7c3a31fce953b96fd477ddd1f437cc7b617d38b999fec45944a80ab58693306f",
       "status": "verified",
       "claims": [
         {
@@ -327,7 +363,7 @@
       ]
     },
     "funifier-create-point": {
-      "configHash": "68c1da1a809c5ad6a360766d257bdc14fefff7162e4072ab2221e0f13d0be0a1",
+      "configHash": "a5d84d1e85e7fe8b3d6af3acb19122243c75456c101b991491ee510716607c4a",
       "status": "verified",
       "claims": [
         {
@@ -353,7 +389,7 @@
       ]
     },
     "funifier-create-quiz": {
-      "configHash": "ccec76679412c2f2a45b3afd30cc0cf266ed29dc1d71c23c6542638819556c7a",
+      "configHash": "dd932897848f30800c71e17acdaf08699dd1c28f5d5b9de618c696bfa88be5b6",
       "status": "verified",
       "claims": [
         {
@@ -379,7 +415,7 @@
       ]
     },
     "funifier-create-scheduler": {
-      "configHash": "841ffa14cc86b91dd2f1d744bbc55def6bfe6de6baf6380fff435625963fdd7e",
+      "configHash": "9f986517a5c5d8caf315b6ee5ce93150666a7f3a0bf45aefe4f46fa883665e38",
       "status": "verified",
       "claims": [
         {
@@ -395,12 +431,12 @@
       ]
     },
     "funifier-create-story": {
-      "configHash": "df98fbfb6f812c49736fb99ab6d6de2575289ce28e915bc95ec994158e3bc9b5",
+      "configHash": "5c53e20e201766c7b2fe29a253c50655cd7fad0fc82edb3543957c79697996bf",
       "status": "verified",
       "claims": []
     },
     "funifier-create-swap": {
-      "configHash": "ef4c5ca6bb0d66976d97dc8a2516da8f112ae0eb6a4e449d678f151dfed646e8",
+      "configHash": "3067da9da8726b0f0191aac05d711e2870dada98044e9fd442bdb2472654d053",
       "status": "verified",
       "claims": [
         {
@@ -416,7 +452,7 @@
       ]
     },
     "funifier-create-trigger": {
-      "configHash": "44204bb97039cb17d5a1d97757562d9fa16baefd5caf0e1f1a6cc0fa0390db4d",
+      "configHash": "21a46732f80324f9662064e8d96528f26c7cfa277f152905fd537be8ef12dab1",
       "status": "verified",
       "claims": [
         {
@@ -452,7 +488,7 @@
       ]
     },
     "funifier-create-virtual-good": {
-      "configHash": "70415901417a63692f7a1325300d2b57644a067dc55917a9e9b64e92bd3c14af",
+      "configHash": "9a78b550bfdd28271fcb1d225da8a6f0a68112735209765b32c34fe0be981c33",
       "status": "verified",
       "claims": [
         {
@@ -468,7 +504,7 @@
       ]
     },
     "funifier-create-webhook": {
-      "configHash": "e9ff0ebe0b9829bf61011b3abc846806a36f0245e4075a34aecdcb86d837c081",
+      "configHash": "cc84a72a02ade14142576f6f66a806e10b400ce624b42509dd9bcb8777424d70",
       "status": "verified",
       "claims": [
         {
@@ -484,7 +520,7 @@
       ]
     },
     "funifier-create-websocket": {
-      "configHash": "66965c501a68223a84647f0fd2f5bb81fb898318e86e901819a7e9a560201096",
+      "configHash": "0689d726bebbe170d03132e53a943978b78392e2c1240a38b147e3813d3f6322",
       "status": "verified",
       "claims": [
         {
@@ -500,7 +536,7 @@
       ]
     },
     "funifier-create-widget": {
-      "configHash": "ed11b1648c6a67e24aa4e6a35a29864a48fa8968b7c5e83275cde8f2464273f2",
+      "configHash": "d4e6e29b2dadbe4838b1dd1e820989c2fc88c7a63fc41e0b871ec725cf2c3296",
       "status": "verified",
       "claims": [
         {
@@ -516,12 +552,12 @@
       ]
     },
     "funifier-date-handling": {
-      "configHash": "82a41d6369f0a1e2ad5e0a09d7c6c318c970436c7b59a0b42611cd6d5e14575e",
+      "configHash": "5a7fd773c2e29a7dacb108bc54262693df7f547cdde225dc95825f1c8dc04651",
       "status": "verified",
       "claims": []
     },
     "funifier-debug": {
-      "configHash": "37c75988e8ddf1c5eb9ef0593a83159410d85a744eb1ff262ba02dc4789fa2a4",
+      "configHash": "e64ae75ed8e9d02014c75480f83888904f408ce87de73e9ab71c142d272fa856",
       "status": "verified",
       "claims": [
         {
@@ -537,7 +573,7 @@
       ]
     },
     "funifier-help": {
-      "configHash": "7af4ce568c8429bd33b797d070dfaed47ad08618ce1074c8532df0aa33fed1c8",
+      "configHash": "25fbe8f89b7cb24e2410477d1c033f6761cd94c777995ae69a21eaf276a4d8ad",
       "status": "verified",
       "claims": [
         {
@@ -553,7 +589,7 @@
       ]
     },
     "funifier-implement-frontend": {
-      "configHash": "cb9700aa8484384f913ef6871ea2a40652c08e394b9e1bfb111706da094c56b5",
+      "configHash": "74c5916808501dd0f10572caf22b92dc083da076493422881060d413cc722681",
       "status": "verified",
       "claims": [
         {
@@ -579,17 +615,17 @@
       ]
     },
     "funifier-import-csv": {
-      "configHash": "24ca1b985f50466dd781e3cb1b9a67f152b748d60735b8e8211b305a4c74b261",
+      "configHash": "9467463bbae7c65363df7137243ff034ccc23dba2426f3e05211ac5bde03ed17",
       "status": "verified",
       "claims": []
     },
     "funifier-manage-indexes": {
-      "configHash": "d4097ecfb403b1df6ea5e2adaf6359b2e663d3ed57f944476abbd9d77debbb1c",
+      "configHash": "bebb7f00e3b8a6eff8276b7264a33dfc6c912a58adc96f3fc8406e8cb1675df3",
       "status": "verified",
       "claims": []
     },
     "funifier-manage-player": {
-      "configHash": "77efa151e25e2672fcea590f4a5f6bf2f77745875a297e79351f544cff04b73f",
+      "configHash": "9d4a397fac4cd79d2a6168ef689ecd8dff76a28324f9a3e67492a1db573d127f",
       "status": "verified",
       "claims": [
         {
@@ -615,7 +651,7 @@
       ]
     },
     "funifier-manage-team": {
-      "configHash": "624ed9b06b109a2a07e4a921537df1f31d91125486c8ab26745a913c39ac1876",
+      "configHash": "63c9ead124e4ffbab71fea8d320e12edc9aa48053bd9607c315bdd350fd1e5ac",
       "status": "verified",
       "claims": [
         {
@@ -630,8 +666,13 @@
         }
       ]
     },
+    "funifier-query-aggregate": {
+      "configHash": "830f98451a47c0e2684aa6d77a218a5f9b3dc4d10ea3281d9a7fcde8c79f7dec",
+      "status": "verified",
+      "claims": []
+    },
     "funifier-upload-file": {
-      "configHash": "93b0c2d388aa465794cedd461006dcc1f93e426001c710cb90cc595d076a5ea1",
+      "configHash": "9c3dcaf7351189c3395ae3ea5ac122d5b470b3e1db0b0fd94384880c0094f19c",
       "status": "verified",
       "claims": []
     }

package/datasource-funifier-docs/knowledge/guides/aggregates.md

@@ -293,6 +293,10 @@ POST /v3/find/{id}
 | Substituição | Cada chave do corpo substitui `"$param:<chave>"` no pipeline diretamente |
 | `context` no script Groovy | Só expõe o player autenticado — `context.get("outro")` retorna `null` |
 | Script vazio | Se o pipeline só usa `"$param:nome"`, o `script` pode ser `""` — não precisa de `prepare()` |
+| Substituição é a nível de **valor** | `"$param:nome"` deve ser a string JSON **inteira**; o valor assume o **tipo** do param (string, número, `Long`, `Date`, array, objeto). Não é interpolação de substring. |
+| Param ausente | Um `"$param:nome"` sem chave correspondente no corpo vira **`null`** → filtro silenciosamente não casa nada. |
+
+**Datas parametrizadas (prepared):** a gramática `{"$date": "-0M-"}` (§4) continua válida **dentro** do pipeline salvo para datas relativas fixas. Para uma data **dinâmica vinda de param**, o padrão é `{"$date": "$param:start"}` no pipeline e o `script` `prepare()` injetando millis: `params.put("start", <Date>.getTime())` (ou um `Date`). A §4 deste guia é o dono único das expressões `$date`; o cálculo da janela no script usa `DateUtil` (`java-libraries.md` §4) — ver também a skill `funifier-date-handling`.
 
 **Listar os parâmetros esperados:**
 ```
@@ -300,21 +304,24 @@ GET /v3/find/{id}/params
 → ["player", "start"]
 ```
 
-**Analisar a execução passo a passo** (mesmo corpo da execução normal):
+**Analisar/inspecionar a definição** (dry-run — mesmo corpo da execução normal):
 ```
 POST /v3/prepared/aggregate/{id}/analyze
 ```
 
+> ⚠️ O `/analyze` é uma **inspeção (dry-run): NÃO roda a agregação no Mongo.** Ele compila e executa o `script` Groovy `prepare()`, aplica a substituição de `$param` e devolve o **pipeline resolvido** — não os documentos resultantes. Para resultado real, use `POST /v3/find/{id}`.
+
 | Campo do retorno | Conteúdo |
 |-------|----------|
-| `script_outputs` | Saídas de `println` do script `prepare()` |
-| `script_exceptions` | Exceções lançadas pelo script Groovy |
-| `obj` | Resultado final do aggregate |
-| `aggregate_step_2`, `aggregate_step_3`, … | Resultado intermediário após cada etapa do pipeline |
+| `script_outputs` | Saídas de `println` do script `prepare()` (capturadas) |
+| `script_exceptions` | Exceções de compilação/execução do script Groovy — **vazio = script ok** |
+| `obj` | A **definição salva** do prepared aggregate (a entidade, não os resultados) |
+| `aggregate_step_2` | O pipeline **após** o `prepare()` rodar (efeitos do script aplicados) |
+| `aggregate_step_3` | O pipeline **após** a substituição dos `"$param:nome"` pelos valores do corpo |
 
 ### Armadilhas conhecidas
 
 - **Executar via `GET /v3/database/aggregate/{id}`** → retorna `null`/`405` silenciosamente, sem mensagem de erro. Correção: `POST /v3/find/{id}`.
 - **Params na query string** → ignorados. Correção: corpo JSON.
 - **Nome de param divergente** → resultado vazio. Correção: conferir com `GET /v3/find/{id}/params`.
-- **Pipeline "perde" os documentos** → execute o `/analyze` e procure a primeira `aggregate_step_N` que retorna vazio.
+- **Script "salvo com sucesso" mas a execução retorna vazio/erro** → o save (`PUT /v3/database/prepared_aggregate`) **não compila** o script; só o `/analyze` (ou a execução) revela falhas. Rode o `/analyze` e inspecione `script_exceptions` (script quebrado) e `aggregate_step_3` (o filtro efetivo após `$param` — se um param faltou, ele vira `null` e o `$match` não casa nada).