funifier-mcp 0.3.17 → 0.3.19

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

@@ -133,3 +133,9 @@ PUT /v3/database/studio_page   { "_id": "...", "display": true, "title": "...",
 
 Acesse `/studio/custom/<slug>` no browser para testar.
 Para CRUD completo: crie página de lista (`display: true`) + formulário (`display: false`, slug com `/:id`).
+
+## Verified References
+
+| Claim | Status | Evidence |
+|-------|--------|----------|
+| DatabaseManager provides MongoDB connection access for aggregate-backed Studio custom pages | ✓ verified | Class:src/main/java/com/funifier/engine/database/DatabaseManager.java:DatabaseManager |

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

@@ -102,3 +102,10 @@ funifier_save type=folder-log payload=<json>
 funifier_folder operation=progress   { "folder": "<root_id>", "player": "player123" }
 funifier_folder operation=inside     { "folder": "<root_id>" }
 ```
+
+## Verified References
+
+| Claim | Status | Evidence |
+|-------|--------|----------|
+| Folder is the entity class for learning trail nodes with unlock_policy, parent, and position fields in funifier-service | ✓ verified | Class:src/main/java/com/funifier/engine/folder/Folder.java:Folder |
+| FolderManager handles folder tree traversal, progress computation, and cascade deletion in funifier-service | ✓ verified | Class:src/main/java/com/funifier/engine/folder/FolderManager.java:FolderManager |

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

@@ -641,3 +641,9 @@ funifier_list type=lastmile
 ```
 
 Simule progresso do jogador até 80% do desafio e verifique se a mensagem é disparada.
+
+## Verified References
+
+| Claim | Status | Evidence |
+|-------|--------|----------|
+| LastMile is the entity class for threshold-triggered motivational messages linked to challenge progress in funifier-service | ✓ verified | Class:src/main/java/com/funifier/engine/lastmile/LastMile.java:LastMile |

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

@@ -124,3 +124,9 @@ funifier_list type=leaderboard search=<title>
 ```
 
 If scores look wrong, reset cache: `GET /v3/leaderboard/reset`
+
+## Verified References
+
+| Claim | Status | Evidence |
+|-------|--------|----------|
+| LeaderBoardManager manages leaderboard ranking computation and cache reset in funifier-service | ✓ verified | Class:src/main/java/com/funifier/engine/leader/LeaderBoardManager.java:LeaderBoardManager |

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

@@ -92,3 +92,10 @@ funifier_list type=level
 ```
 
 Confirme que os níveis estão em ordem crescente de `minPoints`.
+
+## Verified References
+
+| Claim | Status | Evidence |
+|-------|--------|----------|
+| Level is the entity class defining level thresholds and point item reference in funifier-service | ✓ verified | Class:src/main/java/com/funifier/engine/level/Level.java:Level |
+| LevelManager tracks player level progression and threshold evaluation | ✓ verified | Class:src/main/java/com/funifier/engine/level/LevelManager.java:LevelManager |

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

@@ -911,3 +911,10 @@ GET /v3/lottery/participants?lottery=<_id>
 ```
 
 To undo: `DELETE /v3/lottery/:id/execute`
+
+## Verified References
+
+| Claim | Status | Evidence |
+|-------|--------|----------|
+| Lottery is the entity class for ticket-based prize draws with drawDate, choiceMethod, and maxWinners in funifier-service | ✓ verified | Class:src/main/java/com/funifier/engine/lottery/Lottery.java:Lottery |
+| LotteryManager handles ticket generation, draw execution, and winner selection in funifier-service | ✓ verified | Class:src/main/java/com/funifier/engine/lottery/LotteryManager.java:LotteryManager |

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

@@ -767,3 +767,9 @@ funifier_save type=mystery payload=<json>
 GET /v3/mystery/evaluate/<_id>?player=<player_id>
 GET /v3/mystery/execute/<_id>?player=<player_id>
 ```
+
+## Verified References
+
+| Claim | Status | Evidence |
+|-------|--------|----------|
+| MysteryBox is the entity class for probability-based instant games with options, win_chart, and requirements in funifier-service | ✓ verified | Class:src/main/java/com/funifier/engine/mystery/MysteryBox.java:MysteryBox |

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

@@ -73,3 +73,9 @@ funifier_list type=notification
 ```
 
 Dispare o evento correspondente e verifique se a notificação é entregue.
+
+## Verified References
+
+| Claim | Status | Evidence |
+|-------|--------|----------|
+| Notification is the entity class for automated player feedback messages with event, scope, and content fields in funifier-service | ✓ verified | Class:src/main/java/com/funifier/engine/notify/Notification.java:Notification |

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

@@ -93,3 +93,10 @@ funifier_list type=point search=<_id>
 ```
 
 Do NOT use `funifier_logs` — that is only for triggers and schedulers.
+
+## Verified References
+
+| Claim | Status | Evidence |
+|-------|--------|----------|
+| PointCategory is the entity class with category, shortName, and techniques fields for defining point types | ✓ verified | Class:src/main/java/com/funifier/engine/point/PointCategory.java:PointCategory |
+| PointManager manages point accumulation and balance queries in funifier-service | ✓ verified | Class:src/main/java/com/funifier/engine/point/PointManager.java:PointManager |

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

@@ -96,3 +96,10 @@ POST /v3/quiz/start   { "quiz": "<id>", "player": "<player_id>" }
 POST /v3/question/log/bulk   [{ "quiz": "<id>", "quiz_log": "<log_id>", "question": "<q_id>", "answer": ["1"], "player": "<player_id>" }]
 POST /v3/quiz/finish  { "quiz_log": "<log_id>" }
 ```
+
+## Verified References
+
+| Claim | Status | Evidence |
+|-------|--------|----------|
+| Quiz is the entity class storing questions and answer configuration in funifier-service | ✓ verified | Class:src/main/java/com/funifier/engine/quiz/Quiz.java:Quiz |
+| QuizManager handles quiz scoring, lifecycle, and player response processing | ✓ verified | Class:src/main/java/com/funifier/engine/quiz/QuizManager.java:QuizManager |

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

@@ -139,3 +139,9 @@ funifier_logs type=scheduler id=<_id>
 ```
 
 Confirme que não há erros de compilação ou execução no stack trace.
+
+## Verified References
+
+| Claim | Status | Evidence |
+|-------|--------|----------|
+| SchedulerManager is the class that manages cron-based script execution in funifier-service | ✓ verified | Class:src/main/java/com/funifier/engine/integration/scheduler/SchedulerManager.java:SchedulerManager |

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

@@ -634,3 +634,9 @@ GET /v3/story/<_id>
 ```
 
 Teste a navegação entre cenas no Studio antes de publicar.
+
+## Verified References
+
+| Claim | Status | Evidence |
+|-------|--------|----------|
+

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

@@ -93,3 +93,9 @@ POST /v3/swap/receive   { "swap": "<swap_id>" }
 POST /v3/swap/counter/offer   { "swap": "<swap_id>", "buyer": "jerry", "offer": [{ "total": 1, "type": 0, "item": "coin" }] }
 POST /v3/swap/counter/offer/accept   { "offer": "<offer_id>" }
 ```
+
+## Verified References
+
+| Claim | Status | Evidence |
+|-------|--------|----------|
+| Swap is the entity class for player-to-player trade offers with seller, rewards, and requires fields in funifier-service | ✓ verified | Class:src/main/java/com/funifier/engine/swap/Swap.java:Swap |

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

@@ -183,3 +183,11 @@ funifier_logs type=trigger id=<_id>
 ```
 
 Confirme que não há erros de compilação ou execução. Se houver, leia o stack trace e corrija o script.
+
+## Verified References
+
+| Claim | Status | Evidence |
+|-------|--------|----------|
+| Achievement constants TYPE_POINT=0, TYPE_CHALLENGE=1, TYPE_VIRTUAL_GOOD=2, TYPE_LEVEL=3 are defined in the Achievement class | ✓ verified | Class:src/main/java/com/funifier/engine/achievement/Achievement.java:Achievement |
+| ActionLog is the entity class for action triggers with fields actionId, userId, attributes (Map), time, and id | ✓ verified | Class:src/main/java/com/funifier/engine/action/ActionLog.java:ActionLog |
+| TriggerManager is the class that manages trigger script execution and lifecycle in funifier-service | ✓ verified | Class:src/main/java/com/funifier/engine/integration/trigger/TriggerManager.java:TriggerManager |

package/skills/funifier/references/create-virtual-good.md

@@ -94,3 +94,9 @@ Para testar uma compra:
 ```
 POST /v3/virtualgoods/purchase   { "player": "<id>", "item": "<item_id>", "total": 1 }
 ```
+
+## Verified References
+
+| Claim | Status | Evidence |
+|-------|--------|----------|
+| CatalogManager is the class managing virtual goods catalog items, pricing, and purchase lifecycle in funifier-service | ✓ verified | Class:src/main/java/com/funifier/engine/catalog/CatalogManager.java:CatalogManager |

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

@@ -70,3 +70,9 @@ funifier_list type=webhook
 ### 5. Testar
 
 Dispare um evento (ex: log uma ação que gera conquista) e verifique se o endpoint externo recebeu o payload.
+
+## Verified References
+
+| Claim | Status | Evidence |
+|-------|--------|----------|
+| Webhook is the entity class for outbound event notifications to external HTTP endpoints in funifier-service | ✓ verified | Class:src/main/java/com/funifier/engine/webhook/Webhook.java:Webhook |

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

@@ -69,3 +69,9 @@ funifier_list type=websocket
 ```
 
 Conecte um cliente WebSocket e dispare um evento para confirmar que as mensagens chegam em tempo real.
+
+## Verified References
+
+| Claim | Status | Evidence |
+|-------|--------|----------|
+| WebSocket is the entity class for real-time bidirectional communication configuration in funifier-service | ✓ verified | Class:src/main/java/com/funifier/engine/websocket/WebSocket.java:WebSocket |

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

@@ -74,3 +74,9 @@ Cole o código de embed na página destino (intranet, LMS, etc.) e verifique que
 funifier_list type=widget
 GET /v3/widget/<_id>
 ```
+
+## Verified References
+
+| Claim | Status | Evidence |
+|-------|--------|----------|
+| Widget is the entity class for embeddable visual gamification components with type, configuration, and display settings in funifier-service | ✓ verified | Class:src/main/java/com/funifier/engine/widget/Widget.java:Widget |

package/skills/funifier/references/date-handling.md

@@ -170,3 +170,9 @@ Não coloque o parâmetro convertido para `Date` dentro de `{ "$date": "$param:s
 - [ ] Em prepared aggregate, usar `"$param:nome"` exatamente como string.
 - [ ] Para data absoluta em prepared aggregate, converter no `script` com `DateUtil.parse`, validar `null`, e substituir o `Date` diretamente em `$gte`/`$lte`.
 - [ ] Testar aggregate direto antes de salvar como prepared aggregate.
+
+## Verified References
+
+| Claim | Status | Evidence |
+|-------|--------|----------|
+

package/skills/funifier/references/debug.md

@@ -90,3 +90,9 @@ Leia o arquivo de doc específico para o módulo com problema:
 - Scheduler → `funifier_read_doc path=modules/scheduler`
 - Aggregate → `funifier_read_doc path=guides/aggregates`
 - Security/Auth → `funifier_read_doc path=modules/security`
+
+## Verified References
+
+| Claim | Status | Evidence |
+|-------|--------|----------|
+| TriggerManager is the entry point for trigger script execution and error capture in funifier-service | ✓ verified | Class:src/main/java/com/funifier/engine/integration/trigger/TriggerManager.java:TriggerManager |

package/skills/funifier/references/help.md

@@ -79,3 +79,9 @@ Baseado na tabela acima, instrua o usuário a usar a skill específica.
 ### 4. Se não encontrar skill específica
 
 Consulte `funifier_read_doc path=index` e leia o módulo relevante diretamente.
+
+## Verified References
+
+| Claim | Status | Evidence |
+|-------|--------|----------|
+| Achievement is the core entity class representing all gamification rewards in funifier-service | ✓ verified | Class:src/main/java/com/funifier/engine/achievement/Achievement.java:Achievement |

package/skills/funifier/references/implement-frontend.md

@@ -122,3 +122,10 @@ await fetch('/v3/database/cycle__c?strict=true', {
 ### 5. Hospedar no Funifier (opcional)
 
 Para arquivos estáticos, leia `funifier_read_doc path=modules/static-repo`.
+
+## Verified References
+
+| Claim | Status | Evidence |
+|-------|--------|----------|
+| PlayerManager handles player authentication and session management in funifier-service | ✓ verified | Class:src/main/java/com/funifier/engine/player/PlayerManager.java:PlayerManager |
+| ActionManager processes action event registration from frontend clients | ✓ verified | Class:src/main/java/com/funifier/engine/action/ActionManager.java:ActionManager |

package/skills/funifier/references/import-csv.md

@@ -73,3 +73,9 @@ Após import, verifique se os registros foram criados:
 ```
 funifier_list type=player search=<nome_importado>
 ```
+
+## Verified References
+
+| Claim | Status | Evidence |
+|-------|--------|----------|
+

package/skills/funifier/references/manage-indexes.md

@@ -83,3 +83,9 @@ Get the index name from `action=list`. The `_id_` index cannot be dropped.
 | Unique email | `{"email": 1}` (uniqueness enforced by MongoDB, not this API) |
 
 For a composite (e.g. `{player: 1, time: -1}` to back filter+sort in one plan), use the Groovy/trigger path shown in the Limitation section — not this tool.
+
+## Verified References
+
+| Claim | Status | Evidence |
+|-------|--------|----------|
+

package/skills/funifier/references/manage-player.md

@@ -80,3 +80,10 @@ GET /v3/player/<_id>/status
 ```
 GET /v3/team/<team_id>/member/add/<player_id>
 ```
+
+## Verified References
+
+| Claim | Status | Evidence |
+|-------|--------|----------|
+| Player is the entity class with _id, name, email, teams, extra fields in funifier-service | ✓ verified | Class:src/main/java/com/funifier/engine/player/Player.java:Player |
+| PlayerManager handles player CRUD, authentication, and status queries in funifier-service | ✓ verified | Class:src/main/java/com/funifier/engine/player/PlayerManager.java:PlayerManager |

package/skills/funifier/references/manage-team.md

@@ -74,3 +74,9 @@ GET /v3/team/sales/status
 ```
 GET /v3/team/sales/member/remove/tom
 ```
+
+## Verified References
+
+| Claim | Status | Evidence |
+|-------|--------|----------|
+| Team is the entity class for player groups with _id, name, members, owner fields in funifier-service | ✓ verified | Class:src/main/java/com/funifier/engine/team/Team.java:Team |

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

@@ -0,0 +1,111 @@
+# funifier-query-aggregate
+
+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
+
+---
+
+## Before starting — find relevant docs
+
+Use the `funifier_search_docs` MCP tool to load only what you need:
+
+```
+funifier_search_docs "aggregate mongodb pipeline query report ad-hoc consulta"
+```
+
+Then read the most relevant results with `funifier_read_doc path=<path>`.
+
+## Primary docs for this skill
+
+If search returns insufficient results, read these directly:
+
+- `funifier_read_doc path=guides/aggregates`
+- `funifier_read_doc path=guides/database-access`
+- `funifier_read_doc path=modules/database`
+
+## Steps
+
+> **Aggregate ad-hoc** = uma consulta **pontual** executada direto numa coleção via `POST /v3/database/{collection}/aggregate`, com o pipeline no corpo. Sem `_id`, sem salvar, sem `$param`, sem `script`. Use para relatórios e exploração. Se você precisa de um pipeline **salvo, parametrizado e reutilizável** (dashboards, `POST /v3/find/<id>`), use a skill `funifier-create-aggregate` (prepared aggregate).
+
+### 1. Definir a consulta
+
+- Qual coleção tem os dados? (ver tabela abaixo)
+- Qual o filtro (`$match`), agrupamento (`$group`), ordenação (`$sort`) e limite (`$limit`)?
+- Precisa juntar coleções? (`$lookup` — ver relações abaixo)
+
+### Coleções principais e relações (para `$lookup`)
+
+| Coleção | Relação-chave |
+|---|---|
+| `player` | `_id` é a ponta de `userId`/`player` — `name`, `teams`, `extra` |
+| `action_log` | `userId` → `player._id`; `actionId` → `action._id` — `attributes`, `time` |
+| `achievement` | `player` → `player._id`; `item` → coleção do `type` (0=Point, 1=Challenge, 2=VirtualGood, 3=Level) |
+| `challenge` | `_id` referenciado por `achievement.item` (type 1) |
+| `catalog_item` | `_id` referenciado por `achievement.item` (type 2) |
+| `point_category` | `_id` referenciado por `achievement.item` (type 0) |
+
+> Em `achievement`, junte por `$player`/`$item` — **não** por `_id` (senão o `$lookup` volta vazio). Campos completos das coleções: `funifier_read_doc path=guides/java-entities`.
+
+### 2. Operadores suportados
+
+`$match`, `$group`, `$sort`, `$limit`, `$lookup`, `$project`, `$unwind`, `$addFields`, `$count`.
+
+### 3. Filtros por data
+
+A gramática de expressões de data Funifier (`{"$date": "-0M-"}` = início do mês, `-0M+` = fim, `-1d-`, ISO-8601, millis) é detalhada em `aggregates.md` §4 (**dono único** das expressões `$date`) — leia com `funifier_read_doc path=guides/aggregates`. Não reescreva a gramática aqui.
+
+> ⚠️ **Use `?strict=true`** no endpoint ad-hoc ao filtrar por data: sem ele, `Date` degrada para número e o `$match` por data falha. Exemplo: `{ "$match": { "time": { "$gte": {"$date": "-0M-"}, "$lte": {"$date": "-0M+"} } } }`.
+
+### 4. Antes de executar: índices e forma da query
+
+1. Liste os campos que dirigem o plano: filtros de `$match`, campos de `$sort`, e `localField`/`foreignField` de cada `$lookup` (atenção ao `foreignField` na coleção `from`).
+2. Cheque/crie índices: `funifier_index action=list collection=<coll>` para cada coleção tocada; crie os single-field faltantes com `funifier_index action=create`. Índice **composto** (ex.: `{player:1,time:-1}`) → o endpoint REST é single-field apenas; use o caminho Groovy `createIndex(...append...)` (ver skill `funifier-manage-indexes`). Não duplique a mecânica de índice aqui.
+3. Boas práticas: `$match` o mais cedo possível · reduza documentos com `$project`/`$match` **antes** do `$lookup` · `$sort` seguido imediatamente de `$limit` · cuidado com explosão de documentos do `$unwind` · garanta o `$lookup.foreignField` indexado.
+4. ⚠️ **Ad-hoc NÃO usa `allowDiskUse`** — um `$match`/`$sort` sem índice em coleção grande tende a ser lento ou falhar. (Prepared aggregate usa `allowDiskUse(true)`; ad-hoc não.)
+
+### 5. Executar
+
+Via MCP:
+```
+funifier_database action=aggregate collection=<coll> pipeline=<json-array>
+```
+
+Via API REST:
+```
+POST /v3/database/{collection}/aggregate?strict=true
+<json-array do pipeline no corpo>
+```
+
+> O GET de listagem (`GET /v3/database/{collection}`) **não ordena** — para ordenar, use sempre `$sort` num aggregate.
+
+### Exemplos
+
+**Top 10 jogadores com mais XP no mês atual** (coleção `achievement`):
+```json
+[
+  {"$match": {"type": 0, "item": "xp", "time": {"$gte": {"$date": "-0M-"}, "$lte": {"$date": "-0M+"}}}},
+  {"$group": {"_id": "$player", "total": {"$sum": "$total"}}},
+  {"$sort": {"total": -1}},
+  {"$lookup": {"from": "player", "localField": "_id", "foreignField": "_id", "as": "p"}},
+  {"$unwind": "$p"},
+  {"$project": {"_id": 1, "player": "$p.name", "total": 1}},
+  {"$limit": 10}
+]
+```
+
+**Jogadores distintos que executaram ações ontem** (coleção `action_log`):
+```json
+[
+  {"$match": {"time": {"$gte": {"$date": "-1d-"}, "$lte": {"$date": "-1d+"}}}},
+  {"$group": {"_id": "$userId"}},
+  {"$lookup": {"from": "player", "localField": "_id", "foreignField": "_id", "as": "p"}},
+  {"$project": {"_id": 1, "playerName": {"$first": "$p.name"}}}
+]
+```
+
+Mais exemplos prontos (médias, distintos, top-N por período) em `aggregates.md` §6 — `funifier_read_doc path=guides/aggregates`.
+
+## Verified References
+
+| Claim | Status | Evidence |
+|-------|--------|----------|
+

package/skills/funifier/references/upload-file.md

@@ -89,3 +89,9 @@ funifier_save type=player payload=<json>
 ```
 DELETE /v3/upload/<upload_id>
 ```
+
+## Verified References
+
+| Claim | Status | Evidence |
+|-------|--------|----------|
+