funifier-mcp 0.2.26 → 0.2.27

package/skills/acquire-funifier-knowledge/references/mcp-call-patterns.md

@@ -0,0 +1,118 @@
+# Padrões de chamada MCP (auditoria read-only)
+
+Padrões recomendados para varrer uma instância Funifier sem modificá-la. Leia na Fase 2–4. Toda chamada aqui é segura (somente leitura). As ferramentas de escrita (`funifier_save`, `funifier_delete`, `funifier_execute`, e `funifier_database` com `insert`/`update`/`delete`/`bulk`, e `funifier_folder operation=progress`) são **proibidas** nesta skill.
+
+## Ferramentas disponíveis
+
+| Ferramenta | Uso na auditoria | Read-only? |
+|-----------|------------------|-----------|
+| `funifier_connect` | Conectar/trocar de instância (só se não houver `funifier.json`/env vars) | escrita de sessão, sem efeito no servidor |
+| `funifier_list` | Inventário: lista resumida (sem scripts) de um dos 18 tipos | sim |
+| `funifier_get` | Detalhe completo de um objeto — use `mode=read` | sim (em `mode=read`) |
+| `funifier_logs` | Saúde de execução de `trigger`/`scheduler` | sim |
+| `funifier_database` | `query`/`aggregate`/`collections` para coleções e modelo de player | sim (só nessas 3 actions) |
+| `funifier_folder` | `inside`/`breadcrumb` para learning trails | sim (NÃO use `progress`) |
+| `funifier_search_docs` | Buscar a semântica de um campo na base de docs | sim |
+
+## Os 18 tipos listáveis
+
+`funifier_list` e `funifier_get` aceitam exatamente estes valores no parâmetro `type`:
+
+```
+trigger, scheduler, aggregate, websocket, widget, custom-page,
+public-endpoint, challenge-aggregate, auth-module, ai-knowledge,
+action, challenge, point, level, leaderboard, quiz,
+virtual-good-catalog, virtual-good-item
+```
+
+Qualquer coisa fora desta lista (webhooks, notifications, competitions, lotteries, mystery boxes, stories, crosswords, swaps, teams, players, custom objects `__c`, folders/trilhas) **não é listável** por `funifier_list` — descubra via `funifier_database action=collections` ou `funifier_folder`.
+
+## Fase 1 — validar conexão
+
+```
+funifier_database  action=collections
+```
+
+Se retornar a lista de coleções, o MCP está conectado. (Alternativa leve: `funifier_list type=trigger limit=1`.) Registre o serverUrl/nome da conexão e a data de hoje como data do snapshot.
+
+## Fase 2 — inventário bruto
+
+Para cada um dos 18 tipos, liste e registre IDs + nomes:
+
+```
+funifier_list  type=trigger
+funifier_list  type=scheduler
+funifier_list  type=challenge
+... (repita para os 18 tipos)
+```
+
+Dicas:
+- O retorno é um **resumo** (sem scripts/código) — ideal para inventário barato.
+- Use `search` para filtrar por nome/entidade/evento/coleção (OR com vírgula): `funifier_list type=trigger search="login, video"`.
+- Use `limit`/`offset` para paginar instâncias grandes; o cabeçalho indica `offset` da próxima página.
+
+Descubra elementos fora do enum:
+
+```
+funifier_database  action=collections
+```
+
+Procure coleções como `webhook`, `notification`, `competition`, `player`, `team`, e custom objects (sufixo `__c`). Cada uma vira fonte de um documento (player/team → `PLAYER_MODEL.md`; webhook/notification → `INTEGRATIONS.md`).
+
+## Fase 3 — detalhamento
+
+Detalhe completo de um objeto (inclui scripts/regras), sem criar arquivos temporários:
+
+```
+funifier_get  type=trigger  id="<id ou nome>"  mode=read
+funifier_get  type=challenge id="<id>"  mode=read
+```
+
+- `mode=read` retorna JSON inline (até ~50k chars). Acima disso, ele salva num arquivo temp e avisa o caminho — use `Read` para inspecionar. **Não** use `mode=edit` (cria arquivos companion para edição, que não é o objetivo).
+- Para limitar o tamanho, peça só os campos necessários: `funifier_get type=trigger id="x" mode=read fields=["name","entity","event","status"]`.
+
+Amostre o modelo de player/team (poucos documentos, só para entender o schema):
+
+```
+funifier_database  action=query  collection=player  limit=3
+funifier_database  action=query  collection=team    limit=5
+```
+
+Para filtros com operadores MongoDB, use `aggregate`:
+
+```
+funifier_database  action=aggregate  collection=player \
+  pipeline=[{"$match": {"active": true}}, {"$limit": 3}]
+```
+
+## Saúde de execução (Fases 3–4)
+
+Logs de um trigger ou scheduler (coletados no detalhamento da Fase 3; alimentam a análise cruzada da Fase 4, `CONCERNS.md` e `SCHEDULERS.md`):
+
+```
+funifier_logs  type=trigger    id="<id>"
+funifier_logs  type=scheduler  id="<id>"
+```
+
+Sinais para `CONCERNS.md`: scheduler `active` mas sem logs recentes; trigger ativo que nunca executou; erros recorrentes nos logs.
+
+## Learning trails (folders)
+
+Não há `funifier_list type=folder`. A partir de um id raiz conhecido (descoberto numa coleção ou citado pelo usuário):
+
+```
+funifier_folder  operation=inside     payload={"folder": "<rootId>"}
+funifier_folder  operation=breadcrumb payload={"folder": "<nodeId>"}
+```
+
+NUNCA use `operation=progress` — ele dispara o trigger `folder_progress` e contamina os dados da instância.
+
+## Consultar a semântica de um campo
+
+Quando não souber o que um campo significa (ex.: `range`, `operator`, `limitPerType` num challenge), busque nos docs em vez de adivinhar:
+
+```
+funifier_search_docs  "challenge range operator"
+```
+
+A skill `funifier` (`skills/funifier/references/`) é a autoridade sobre semântica — prefira-a a inferir do objeto vivo.

package/skills/funifier/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: funifier
+description: >
+  Routes to the correct workflow for any Funifier task — creating or managing actions,
+  challenges, points, leaderboards, triggers, schedulers, aggregates, quizzes, virtual goods,
+  custom pages, and frontend implementation. Check this skill first before using any funifier_* MCP tool.
+---
+
+# Funifier
+
+## ⚠ Rule
+
+**Before using any `funifier_*` MCP tool or starting any Funifier task**, find the matching row in the routing table below and **read the referenced file before acting**. Reference files contain the correct field values, enum tables, and examples that prevent common errors.
+
+Only proceed directly with MCP tools when no row matches.
+
+## Usage
+
+1. Identify what the user wants to do
+2. Find the matching row in the routing table below
+3. Read the file listed in the Reference column
+4. Follow the workflow in that file
+
+For general questions with no matching task, run lexical search:
+
+```bash
+npx funifier-mcp search "<user question>"
+```
+
+## Routing Table
+
+| When to use | Reference |
+|-------------|-----------|
+| Create a Funifier trigger — guided workflow from entity/event selection to Groovy code generation | `references/create-trigger.md` |
+| Create a Funifier scheduler — guided workflow from naming and cron expression to Groovy code generation | `references/create-scheduler.md` |
+| Create a Funifier prepared aggregate — guided workflow for building MongoDB aggregate pipelines for reports and dashboards | `references/create-aggregate.md` |
+| Create a Funifier challenge — missions with action rules and point rewards | `references/create-challenge.md` |
+| Create a Funifier action — define trackable player behaviors with attributes | `references/create-action.md` |
+| Create a Funifier point category — XP, coins, or custom metrics | `references/create-point.md` |
+| Create Funifier levels — progression system based on accumulated points | `references/create-level.md` |
+| Create a Funifier leaderboard — rankings by points, actions, or attributes | `references/create-leaderboard.md` |
+| Create a Funifier quiz — questionnaires with multiple-choice questions | `references/create-quiz.md` |
+| Create a Funifier virtual good — catalog items players can purchase with points | `references/create-virtual-good.md` |
+| Create a Funifier Studio custom page — guided workflow for building admin dashboards, CRUDs, reports, and KPI pages using AngularJS + Bootstrap | `references/create-custom-page.md` |
+| Implement frontend code that consumes the Funifier API — authentication, data fetching, aggregate consumption, and static hosting on Funifier subdomain | `references/implement-frontend.md` |
+| Debug a Funifier resource — systematic diagnosis of triggers, schedulers, aggregates, and other Funifier components | `references/debug.md` |
+| Get help with Funifier — routes to the right documentation or skill based on your question | `references/help.md` |
+| Register and manage Funifier players — CRUD workflow for participant onboarding, team assignment, extra-field management, and status queries; use at the start of every project to set up participants | `references/manage-player.md` |
+| Create and manage Funifier teams — group players for collective challenges, team rankings, and collaborative goals; use when organizing players into competing or collaborating groups, not when only individual player setup is needed | `references/manage-team.md` |
+| Create a Funifier competition — timed ranking contests with player enrollment, position-based rewards, and execution; use when you need player sign-up, prizes by finish position, or a scheduled end date, not when an always-on leaderboard is enough | `references/create-competition.md` |
+| Create a Funifier learning trail (folder) — hierarchical courses with content types, progress tracking, conditional unlock policies, and trigger events; use when structuring sequenced training journeys, not when standalone challenges are enough | `references/create-folder.md` |
+| Create a Funifier lottery — ticket-based prize draws with configurable draw dates, max winners, and rewards; use when running promotional prize drawings where players earn tickets, not when probability-based instant games are needed (use mystery box) | `references/create-lottery.md` |
+| Create a Funifier mystery box — probability-based instant games (spin wheel, scratch card, coin flip) with configurable odds and rewards; use for random reward mechanics, not for ticket-based draws with scheduled dates (use lottery) | `references/create-mystery.md` |
+| Create a Funifier interactive story — branching narratives with player choices, scenes, and media for training or campaigns; use when building choose-your-own-adventure experiences, not when a linear quiz or folder trail is sufficient | `references/create-story.md` |
+| Create a Funifier crossword puzzle game — themed word games with custom clues and grid positions for educational onboarding or marketing; use when building interactive word-based games, not when a multiple-choice quiz is enough | `references/create-crossword.md` |
+| Create a Funifier notification — standalone automated player feedback messages for game events; use when managing notification records directly via API, not when configuring notifications inline within challenge or competition payloads | `references/create-notification.md` |
+| Create a Funifier last-mile notification — motivational messages triggered when a player reaches a configured progress threshold near a challenge goal; use to boost completion rates, not as a general notification system | `references/create-lastmile.md` |
+| Create a Funifier webhook — push real-time event payloads to external endpoints (BI, CRM, Slack, Teams); use when external systems need event-driven data from Funifier, not when in-app live updates are needed (use websocket) | `references/create-webhook.md` |
+| Create a Funifier websocket configuration — real-time bidirectional communication for live competitions, instant player feedback, and chat; use for in-app live updates, not for pushing to external systems (use webhook) | `references/create-websocket.md` |
+| Create a Funifier widget — embeddable visual components (rankings, challenge lists, player status, virtual stores) for integrating gamification displays into existing web systems like intranets, CRMs, or LMS platforms | `references/create-widget.md` |
+| Create a Funifier swap — player-to-player trade offers for items or points with counter-proposal support; use when enabling peer trading or social exchange mechanics, not when a standard virtual good store purchase is sufficient | `references/create-swap.md` |
+| Create and manage Funifier custom objects — domain-specific collections with the __c suffix for storing business entities (products, venues, categories) that do not fit standard modules; accessible via API, triggers, and schedulers | `references/create-custom-object.md` |
+| Configure Funifier security settings — roles, scopes, app tokens, and auth parameters; use when setting up access control, fixing missing database scope errors, or configuring token expiry; not for writing frontend login code (use funifier-implement-frontend) | `references/configure-security.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) | `references/import-csv.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) | `references/upload-file.md` |
+
+## Documented Modules
+
+| Module | Description |
+|--------|-------------|
+| Auth | Login de jogadores, geração de tokens JWT, autenticação via API |
+| Security | Configuração do documento de segurança — apps com app_secret, roles de jogador, escopos, pipeline de autorização e emissão de tokens Bearer |
+| Player | Cadastro e gestão de utilizadores da aplicação |
+| Database | CRUD em qualquer coleção, queries MongoDB, aggregates |
+| Custom Object | Criar tabelas/coleções próprias (sufixo ) para dados de negócio |
+| Upload | Upload de imagens e ficheiros (avatar, documentos, etc.) |
+| Trigger | Escrever funções Java que executam no servidor quando eventos acontecem |
+| Scheduler | Agendar tarefas automáticas (cron jobs, rotinas periódicas) |
+| Public Endpoint | Criar APIs REST customizadas acessíveis sem autenticação |
+| Webhook | Enviar dados para sistemas externos quando eventos acontecem |
+| Patterns | Design patterns de implementação (signup, etc.) baseados em experiência real |
+
+## MCP
+
+If Funifier MCP tools are available (`funifier_list`, `funifier_save`, `funifier_get`, `funifier_logs`):
+- Use MCP for live server data
+- Use docs for correct patterns and syntax
+- Never learn patterns from existing live resources — docs are authoritative

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

@@ -0,0 +1,96 @@
+# funifier-configure-security
+
+Configure Funifier security settings — roles, scopes, app tokens, and auth parameters; use when setting up access control, fixing missing database scope errors, or configuring token expiry; not for writing frontend login code (use funifier-implement-frontend)
+
+---
+
+## Before starting — find relevant docs
+
+Run lexical search to load only what you need:
+
+```bash
+npx funifier-mcp search "security role scope token auth app permission basic bearer access-control" --skill funifier-configure-security
+```
+
+Read only files returned with score > 0.5 (this threshold is printed in the search output).
+
+## Primary docs for this skill
+
+If search returns insufficient results, read directly:
+
+- `datasource-funifier-docs/knowledge/modules/security.md`
+
+## Steps
+
+### Regras críticas
+
+- **`timeout: ""` (string vazia) causa NPE** no auth — omita o campo ou use `"7d"`, nunca string vazia
+- **Scope `database` é palavra-chave obrigatória** para `/v3/database` — `write_all` sozinho não basta
+- **PUT é upsert total** — sempre inclua roles E apps existentes, senão serão perdidos
+- **Token Basic da gamificação (público):** `base64(API_KEY + ":")` (dois-pontos no final, sem secret)
+- **Token Basic do app (server-side):** `base64(API_KEY + ":" + APP_SECRET)`
+
+### Scopes importantes
+
+| Scope | Descrição |
+|---|---|
+| `read_all` | Leitura em todas as coleções |
+| `write_all` | Escrita em todos os endpoints |
+| `delete_all` | Exclusão em todos os endpoints |
+| `database` | **Obrigatório** para `/v3/database` (sem ele, escrita silencia sem erro) |
+| `write_database_<coll>` | Escrita em coleção específica |
+
+---
+
+## Steps
+
+### 1. Obter configuração atual de segurança
+
+```
+GET /v3/database/security/<API_KEY>?strict=true
+Authorization: Bearer <studio_token>
+```
+
+### 2. Ler a documentação do módulo
+
+```
+datasource-funifier-docs/knowledge/modules/security.md
+```
+
+### 3. Definir roles e apps
+
+Configuração padrão para projetos com frontend:
+```json
+{
+  "_id": "API_KEY",
+  "roles": [
+    { "name": "public", "scope": "read_all" },
+    { "name": "player", "scope": "read_all, write_all, delete_all, database", "timeout": "7d" }
+  ],
+  "apps": [
+    { "name": "Backend App", "app_secret": "<GUID>", "scope": "read_all, write_all, delete_all, database" }
+  ]
+}
+```
+
+### 4. Gerar GUID para app secret (se necessário)
+
+```
+GET /v3/util/guid/new
+Authorization: Bearer <studio_token>
+```
+
+### 5. Salvar via PUT (não POST)
+
+```
+PUT /v3/database/security   <payload acima>
+Authorization: Bearer <studio_token>
+```
+
+### 6. Verificar
+
+```
+GET /v3/database/security/<API_KEY>?strict=true
+```
+
+Teste login de jogador e confirme que o token retornado tem os scopes corretos.

package/skills/{funifier-create-action/SKILL.md → funifier/references/create-action.md}

@@ -1,32 +1,7 @@
----
-name: funifier-create-action
-description: Create a Funifier action — define trackable player behaviors with attributes
----
-
 # funifier-create-action
 
 Create a Funifier action — define trackable player behaviors with attributes
 
-## Persona e Qualidade de Código
-
-A partir de agora, atue como um **desenvolvedor de software sênior altamente experiente**, especializado em **geração de código limpo, legível e de fácil manutenção**. Suas soluções devem seguir rigorosamente as **boas práticas da indústria**, **padrões de projeto** e **arquiteturas modernas**, sempre **evitando overengineering**.
-
-### Ao lidar com qualquer código — seja refatorando ou criando do zero — siga este processo:
-
-1. **Analise cuidadosamente o problema ou o código existente.**
-2. **Raciocine passo a passo** antes de escrever qualquer linha de código.
-3. **Identifique problemas (em caso de refatoração) ou requisitos (em caso de código novo).**
-4. **Defina prioridades e estratégias com base em princípios sólidos de engenharia.**
-5. **Justifique tecnicamente cada decisão**, com base em fundamentos como:
-   - **SOLID**
-   - **DRY (Don't Repeat Yourself)**
-   - **KISS (Keep It Simple, Stupid)**
-   - **YAGNI (You Aren't Gonna Need It)**
-
-Só então prossiga com a implementação.
-
-> **Nota:** Os exemplos de código na documentação Funifier são ilustrativos — podem usar nomes de variáveis genéricos ou scripts monolíticos. Sempre melhore-os: use nomes descritivos, extraia métodos especializados para lógicas complexas e mantenha cada função com responsabilidade única.
-
 ---
 
 ## Before starting — find relevant docs
@@ -116,11 +91,3 @@ funifier_list type=action search=<_id>
 ```
 
 Do NOT use `funifier_logs` — that is only for triggers and schedulers.
-
-## MCP
-
-If Funifier MCP tools are available (`funifier_list`, `funifier_save`, `funifier_get`, `funifier_logs`):
-- Use MCP for live server data
-- Use docs for correct patterns and syntax
-- Never learn patterns from existing live resources — docs are authoritative
-- **For any new Funifier task, check `/funifier-index` first** — there may be a skill with the correct enums, examples, and workflow already defined

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

@@ -0,0 +1,144 @@
+# funifier-create-aggregate
+
+Create a Funifier prepared aggregate — guided workflow for building MongoDB aggregate pipelines for reports and dashboards
+
+---
+
+## Formato do payload (obrigatório)
+
+Funifier armazena código como **strings JSON escapadas**. Ao montar o payload do `funifier_save`:
+
+- **Quebra de linha** → `\n` (nunca newline literal dentro da string)
+- **Aspas duplas** dentro do código → `\"`
+- **Backslash** → `\\` (regex `\b` vira `\\b`; dentro de Groovy com string-building pode exigir `\\\\b`)
+- **Tab** → `\t` (se usar)
+- **Pipelines de aggregate** vão como **string JSON** (não objeto aninhado) — serialize o array inteiro
+
+A regra prática: monte o objeto em JavaScript normalmente e passe por `JSON.stringify` — o MCP faz isso automaticamente quando você entrega o payload como JSON. **Nunca** cole código multilinha cru no meio do JSON.
+
+### Exemplo 1 — custom-page (html + angularjs script)
+
+```json
+{
+  "title": "Ciclos",
+  "slug": "studio/custom/ciclos",
+  "html": "<div class=\"row\">\n  <div class=\"col-md-12\">\n    <h2>Ciclos</h2>\n  </div>\n</div>\n",
+  "script": "$scope.all = [];\n$scope.loading = false;\n\n$scope.list = function () {\n  $scope.loading = true;\n};\n$scope.list();\n"
+}
+```
+
+### Exemplo 2 — aggregate preparado (pipeline JSON + script Groovy)
+
+```json
+{
+  "_id": "extrato",
+  "title": "Extrato de Pontos",
+  "collection": "extrato",
+  "aggregate": "[\n  {\n    \"$match\": { \"player\": \"$param:player\" }\n  },\n  {\n    \"$sort\": { \"time\": -1 }\n  }\n]",
+  "script": "void prepare(aggregations, params) {\n    if (context.get(\"player\") != null) {\n        params.put(\"player\", context.get(\"player\"));\n    } else {\n        params.put(\"player\", \"NAO_EXISTE\");\n    }\n}\n"
+}
+```
+
+Note que `aggregate` é uma **string** contendo JSON serializado (com `\n` e `\"` escapados), **não** um array nativo. Mesma regra vale para `script` em triggers/schedulers/aggregates e `html`/`script` em custom-pages.
+
+---
+
+## Before starting — find relevant docs
+
+Run lexical search to load only what you need:
+
+```bash
+npx funifier-mcp search "aggregate mongodb pipeline report dashboard query prepared" --skill funifier-create-aggregate
+```
+
+Read only files returned with score > 0.5 (this threshold is printed in the search output).
+
+## Primary docs for this skill
+
+If search returns insufficient results, read directly:
+
+- `datasource-funifier-docs/knowledge/guides/aggregates.md`
+- `datasource-funifier-docs/knowledge/guides/database-access.md`
+- `datasource-funifier-docs/knowledge/modules/database.md`
+
+## Steps
+
+### Coleções principais
+
+| Coleção | Conteúdo chave |
+|---|---|
+| `achievement` | Conquistas — `type`: 0=Point, 1=Challenge, 2=VirtualGood, 3=Level |
+| `action_log` | Ações executadas — `actionId`, `userId`, `attributes`, `time` |
+| `player` | Jogadores — `_id`, `name`, `teams`, `extra` |
+| `challenge` | Desafios — `_id`, `challenge`, `rules`, `points` |
+| `point_category` | Tipos de ponto — `_id`, `category`, `shortName` |
+| `catalog_item` | Loja virtual — `_id`, `catalogId`, `name`, `requires` |
+
+### Expressões de data Funifier
+
+| Expressão | Significado |
+|---|---|
+| `{"$date": "-0d-"}` | Início do dia atual |
+| `{"$date": "-0M-"}` | Início do mês atual |
+| `{"$date": "-0M+"}` | Fim do mês atual |
+| `{"$date": "-0y-"}` | Início do ano atual |
+| `{"$date": "-1d-"}` | Início do dia anterior |
+
+---
+
+## Steps
+
+### 1. Identificar a necessidade
+
+- Qual collection tem os dados? (ver tabela acima)
+- Qual o filtro? (período, jogador, tipo de conquista)
+- Qual o agrupamento? (por jogador, por dia, por equipe)
+- Qual ordenação e limite?
+
+### 2. Verificar se já existe
+
+```
+funifier_list type=aggregate search=<titulo>
+```
+
+### 3. Construir e testar o pipeline
+
+Top 10 jogadores com mais pontos no mês:
+```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}
+]
+```
+
+Testar diretamente antes de registrar:
+```
+POST /v3/database/achievement/aggregate
+```
+
+### 4. Registrar como Prepared Aggregate
+
+```json
+{
+  "_id": "top_players_month",
+  "title": "Top Players Month",
+  "collection": "achievement",
+  "aggregate": "[{\"\$match\":{\"type\":0,\"item\":\"xp\"}},{\"\$group\":{\"_id\":\"\$player\",\"total\":{\"\$sum\":\"\$total\"}}},{\"\$sort\":{\"total\":-1}},{\"\$limit\":10}]",
+  "script": ""
+}
+```
+
+```
+funifier_save type=aggregate payload=<json>
+```
+
+### 5. Validar
+
+```
+funifier_list type=aggregate search=<titulo>
+```

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

@@ -0,0 +1,116 @@
+# funifier-create-challenge
+
+Create a Funifier challenge — missions with action rules and point rewards
+
+---
+
+## Before starting — find relevant docs
+
+Run lexical search to load only what you need:
+
+```bash
+npx funifier-mcp search "challenge mission reward rules action points gamification" --skill funifier-create-challenge
+```
+
+Read only files returned with score > 0.5 (this threshold is printed in the search output).
+
+## Primary docs for this skill
+
+If search returns insufficient results, read directly:
+
+- `datasource-funifier-docs/knowledge/modules/challenge.md`
+- `datasource-funifier-docs/knowledge/modules/action.md`
+- `datasource-funifier-docs/knowledge/modules/point.md`
+
+## Steps
+
+### Regras críticas
+
+- **Dependências**: Actions e Points devem existir **antes** de criar o challenge
+- `techniques` é **obrigatório** — use `["GT35"]` (Quest List) na maioria dos casos
+- `range` é necessário quando há mais de uma rule
+
+### Referência rápida
+
+| Campo | Enum | Significado |
+|---|---|---|
+| `range` | `0` | Complete All (todas as rules) |
+| `range` | `1` | Complete Any (qualquer rule) |
+| `range` | `2` | Complete All in Order |
+| `rules[].operator` | `5` | >= (padrão — N ou mais vezes) |
+| `rules[].operator` | `1` | = (exatamente N vezes) |
+| `limitTimeScale` | `5` | Day | `6` = Week | `7` = Month |
+| `limitPerType` | `0` | Player | `1` = Team | `2` = Global |
+
+---
+
+## Steps
+
+### 1. Confirmar dependências
+
+```
+funifier_list type=action search=<actionId>
+funifier_list type=point search=<category>
+```
+
+### 2. Verificar se já existe
+
+```
+funifier_list type=challenge search=<nome>
+```
+
+### 3. Construir o payload
+
+Challenge simples:
+```json
+{
+  "challenge": "Watch Video",
+  "description": "Watch a video to earn 10 xp",
+  "techniques": ["GT35"],
+  "rules": [{ "actionId": "watch_video", "operator": 5, "total": 1 }],
+  "points": [{ "total": 10, "category": "xp", "operation": 0 }]
+}
+```
+
+Com filtro de atributo:
+```json
+{
+  "challenge": "Sell 10 Books",
+  "techniques": ["GT35"],
+  "rules": [{
+    "actionId": "sell",
+    "operator": 5,
+    "total": 10,
+    "filters": [{ "param": "product", "operator": 1, "value": "book" }]
+  }],
+  "points": [{ "total": 25, "category": "xp", "operation": 0 }]
+}
+```
+
+Com limite de frequência (1x por dia):
+```json
+{
+  "challenge": "Daily Check-in",
+  "techniques": ["GT35"],
+  "rules": [{ "actionId": "checkin", "operator": 5, "total": 1 }],
+  "points": [{ "total": 5, "category": "xp", "operation": 0 }],
+  "limitTotal": 1,
+  "limitPerType": 0,
+  "limitTimeAmount": 1,
+  "limitTimeScale": 5
+}
+```
+
+### 4. Salvar
+
+```
+funifier_save type=challenge payload=<json>
+```
+
+### 5. Validar
+
+```
+funifier_get type=challenge id=<_id>
+```
+
+Não use `funifier_logs` — isso é só para triggers e schedulers.