funifier-mcp 0.2.26 → 0.2.28

package/skills/acquire-funifier-knowledge/assets/templates/OVERVIEW.md

@@ -0,0 +1,86 @@
+# Funifier — Overview da Instância
+
+> Snapshot gerado pela skill `acquire-funifier-knowledge`. Substitua todos os `{{...}}`. Não deixe seções vazias — use `[TODO]`/`[ASK USER]`.
+
+## Core (Obrigatório)
+
+### Identificação
+- **Instância:** {{nome/serverUrl}}
+- **Data do snapshot:** {{YYYY-MM-DD}}
+- **Escopo do mapeamento:** {{completo | foco em <área>}}
+
+### Contagens agregadas
+Contagem por tipo listável (preencha 0 quando não houver — não omita):
+
+| Tipo | Qtde |
+|------|------|
+| trigger | {{n}} |
+| scheduler | {{n}} |
+| action | {{n}} |
+| challenge | {{n}} |
+| point | {{n}} |
+| level | {{n}} |
+| leaderboard | {{n}} |
+| quiz | {{n}} |
+| virtual-good-catalog | {{n}} |
+| virtual-good-item | {{n}} |
+| public-endpoint | {{n}} |
+| custom-page | {{n}} |
+| widget | {{n}} |
+| websocket | {{n}} |
+| aggregate | {{n}} |
+| challenge-aggregate | {{n}} |
+| auth-module | {{n}} |
+| ai-knowledge | {{n}} |
+
+### Elementos fora do enum (via coleções)
+| Elemento | Coleção | Qtde aprox. |
+|----------|---------|-------------|
+| {{webhook/notification/competition/...}} | {{collection}} | {{n}} |
+
+### Mapa de Arquitetura
+
+Visão macro de "o que dispara/premia/alimenta/chama o quê". **Regras:** toda aresta vem de um campo real (trigger `entity`/`event`, recompensa de challenge, métrica de leaderboard, preço de virtual-good...) e o mesmo fato aparece no doc da categoria; relação incerta = `-.->` `[ASK USER]`; categoria com >8 objetos = um único nó com a contagem (`challenges["challenges (×24)"]`). Verbos permitidos: `dispara`, `premia`, `alimenta`, `exige`, `lê`, `chama`. Substitua os `{{...}}` por IDs de nó saneados (`[A-Za-z0-9_]`) e remova as arestas sem relação comprovada.
+
+```mermaid
+flowchart LR
+  subgraph Acoes["Ações & Eventos"]
+    {{act_id}}["{{nome}} · action"]
+  end
+  subgraph Automacao["Automação"]
+    {{trigger_id}}["{{nome}} · trigger"]
+    {{scheduler_id}}["{{nome}} · scheduler"]
+  end
+  subgraph Mecanicas["Mecânicas"]
+    {{challenge_id}}["{{nome}} · challenge"]
+    {{level_id}}["{{nome}} · level"]
+  end
+  subgraph Recompensas["Recompensas"]
+    {{point_id}}["{{nome}} · point"]
+    {{vg_id}}["{{nome}} · virtual-good"]
+  end
+  subgraph Visualizacao["Visualização"]
+    {{leaderboard_id}}["{{nome}} · leaderboard"]
+    {{aggregate_id}}["{{nome}} · aggregate"]
+  end
+  subgraph Integracoes["Integrações"]
+    {{endpoint_id}}["{{nome}} · public-endpoint"]
+  end
+
+  {{act_id}} -->|alimenta| {{challenge_id}}
+  {{trigger_id}} -->|premia| {{point_id}}
+  {{challenge_id}} -->|premia| {{vg_id}}
+  {{point_id}} -->|alimenta| {{leaderboard_id}}
+  {{level_id}} -->|exige| {{point_id}}
+  {{aggregate_id}} -->|lê| {{point_id}}
+  {{scheduler_id}} -.->|chama [ASK USER]| {{endpoint_id}}
+```
+
+## Extended (Opcional)
+- Versão/plano da instância, se conhecido.
+- Principais áreas funcionais identificadas (resumo de 2-3 linhas).
+
+## Evidence
+- `funifier_list type=<cada um dos 18 tipos>`
+- `funifier_database action=collections`
+- Mapa de arquitetura: cada aresta é evidenciada pelo objeto/campo que a sustenta, documentado no doc da categoria correspondente ({{ex.: TRIGGERS.md #id, GAME_MECHANICS.md #id}}).

package/skills/acquire-funifier-knowledge/assets/templates/PLAYER_MODEL.md

@@ -0,0 +1,31 @@
+# Funifier — Modelo de Player
+
+> Derivado de amostragem das coleções `player`/`team` (read-only) e dos auth modules. Não invente atributos — liste só os que aparecem nos documentos amostrados. Intenção de negócio → `[ASK USER]`.
+
+## Core (Obrigatório)
+
+### Atributos custom de player
+Campos além dos padrão observados na amostra de `collection=player`:
+
+| Campo | Tipo observado | Exemplo (anonimizado) | Propósito inferido |
+|-------|----------------|-----------------------|--------------------|
+| {{campo}} | {{string/number/bool/...}} | {{ex}} | {{para quê | [ASK USER]}} |
+
+### Segmentações / Teams
+| Segmentação | Fonte (campo/coleção) | Valores observados |
+|-------------|-----------------------|--------------------|
+| {{team/hierarquia/extra}} | {{collection.field}} | {{valores}} |
+
+### Auth modules
+| _id | title | Propósito | Status |
+|-----|-------|-----------|--------|
+| {{id}} | {{título}} | {{login/SSO/...}} | {{ativo?}} |
+
+## Extended (Opcional)
+- Volume aproximado de players (via `funifier_database`).
+- Propriedades estendidas usadas por challenges/leaderboards como filtro.
+
+## Evidence
+- `funifier_database action=query collection=player limit=3`
+- `funifier_database action=query collection=team limit=5`
+- `funifier_list type=auth-module`

package/skills/acquire-funifier-knowledge/assets/templates/SCHEDULERS.md

@@ -0,0 +1,25 @@
+# Funifier — Schedulers
+
+> Tarefas agendadas (cron, Groovy). Scheduler `active: false` que parece importante → `CONCERNS.md` + `[ASK USER]`.
+
+## Core (Obrigatório)
+
+| _id | name | cron | Ação executada | Última execução | Status |
+|-----|------|------|----------------|-----------------|--------|
+| {{id}} | {{nome}} | {{expr cron}} | {{o que faz}} | {{via funifier_logs | [TODO]}} | {{active?}} |
+
+### Detalhe por scheduler (quando relevante)
+**{{name}}** (`{{_id}}`)
+- Cron: `{{expressão}}` ({{interpretação em linguagem natural}})
+- O que faz: {{resumo do script}}
+- Chama endpoint/coleção: {{refs, se houver}}
+- Saúde: {{logs recentes? erros? | [TODO]}}
+
+## Extended (Opcional)
+- Próxima execução estimada (se derivável do cron).
+- Schedulers que dependem de dados produzidos por triggers/aggregates.
+
+## Evidence
+- `funifier_list type=scheduler`
+- `funifier_get mode=read type=scheduler id=<...>`
+- `funifier_logs type=scheduler id=<...>`

package/skills/acquire-funifier-knowledge/assets/templates/TECHNIQUES_AND_PATTERNS.md

@@ -0,0 +1,26 @@
+# Funifier — Técnicas e Padrões de Jogo
+
+> Inferência cruzada — NÃO introduz dados novos. Cada técnica afirmada DEVE listar os IDs que a implementam. Sem objeto que a sustente, a técnica está ausente. Use a taxonomia em `references/game-techniques-taxonomy.md`.
+
+## Core (Obrigatório)
+
+Para cada técnica presente, use este formato:
+
+### {{Nome da técnica}}
+{{Presente | Parcial | Ausente}}. {{Como é implementada nesta instância}}
+- {{Objeto e ID que implementa}}
+- {{Objeto e ID que implementa}}
+
+(Repita para cada técnica observada: loops de feedback, progressão, competição, colaboração, recompensas/economia, conquistas/status, escassez/urgência, surpresa/sorte, narrativa, onboarding.)
+
+### Técnicas ausentes (notáveis)
+Liste técnicas comuns que NÃO foram encontradas, se relevante para o diagnóstico — ex.: "Colaboração: ausente — nenhum team ou challenge coletivo configurado."
+
+## Extended (Opcional)
+- Padrões de design observados (ex.: signup flow, daily streak) com os triggers/schedulers que os compõem.
+- Lacunas: técnicas iniciadas mas incompletas (ex.: points sem leaderboard que os exiba).
+
+## Evidence
+Liste, por técnica, as chamadas/IDs que sustentam a inferência. Ex.:
+- Progressão → `funifier_list type=level`; `funifier_get type=point id=<...>`
+- Competição → `funifier_list type=leaderboard`

package/skills/acquire-funifier-knowledge/assets/templates/TRIGGERS.md

@@ -0,0 +1,27 @@
+# Funifier — Triggers
+
+> Eventos que disparam ações server-side (Groovy). Não escreva "provavelmente dispara X" — cite `entity`/`event` exatos. Trigger ativo sem logs → mova para `CONCERNS.md`.
+
+## Core (Obrigatório)
+
+| _id | name | entity | event | Condições | Ações executadas | Status |
+|-----|------|--------|-------|-----------|------------------|--------|
+| {{id}} | {{nome}} | {{entity}} | {{event}} | {{condições do script}} | {{o que faz}} | {{ativo/inativo}} |
+
+### Detalhe por trigger (quando relevante)
+Para triggers com lógica não-trivial, documente o resumo do script:
+
+**{{name}}** (`{{_id}}`)
+- Origem: `{{entity}}` / `{{event}}`
+- O que faz: {{resumo do comportamento, baseado no script Groovy}}
+- Objetos afetados: {{point/challenge/coleção que ele toca}}
+- Última execução conhecida: {{timestamp via funifier_logs | [TODO]}}
+
+## Extended (Opcional)
+- Triggers agrupados por evento de origem.
+- Dependências entre triggers (um cria um log que outro consome).
+
+## Evidence
+- `funifier_list type=trigger`
+- `funifier_get mode=read type=trigger id=<...>`
+- `funifier_logs type=trigger id=<...>`

package/skills/acquire-funifier-knowledge/references/funifier-inventory-checklist.md

@@ -0,0 +1,81 @@
+# Checklist de inventário Funifier
+
+Use na Fase 2 para garantir cobertura. Para cada categoria, faça a chamada MCP indicada e responda as perguntas. Marque `[TODO]` se a chamada falhar e `[ASK USER]` se a resposta depender de intenção de negócio. Cada categoria indica em qual documento o resultado entra.
+
+## Mecânicas de jogo → `GAME_MECHANICS.md`
+
+**Pontos** (`funifier_list type=point`)
+- Quantas categorias de ponto existem? Quais `category` e `shortName`?
+- Cada categoria é XP, moeda resgatável, ou métrica interna?
+
+**Níveis** (`funifier_list type=level`)
+- Quantos níveis? Qual `minPoints` e `position` de cada um?
+- A qual categoria de ponto a progressão está atrelada?
+
+**Challenges / achievements** (`funifier_list type=challenge` → `funifier_get mode=read`)
+- Quantos challenges? Quais regras (`rules`) e recompensas (`points`) de cada um?
+- Algum é inatingível (regra impossível, ação inexistente)? → `CONCERNS.md`
+- Há cadeias que representam "missions"? → marque `[ASK USER]`
+
+**Actions** (`funifier_list type=action`)
+- Quais comportamentos rastreáveis existem? Quais `attributes`?
+- Alguma action está definida mas não é referenciada por nenhum challenge/trigger? → `CONCERNS.md`
+
+**Quizzes** (`funifier_list type=quiz`)
+- Quantos quizzes? Qual o critério de aprovação (`grade`)?
+
+**Virtual goods** (`funifier_list type=virtual-good-catalog` e `type=virtual-good-item`)
+- Quais catálogos e itens? Itens `active`? Preço (`amount`) e categoria de ponto usada?
+- Algum item funciona como badge (recompensa simbólica)?
+
+**Aggregates** (`funifier_list type=aggregate`, `type=challenge-aggregate`)
+- Quais pipelines alimentam dashboards/relatórios? Sobre qual `collection`?
+
+## Triggers → `TRIGGERS.md`
+
+`funifier_list type=trigger` → `funifier_get mode=read` nos relevantes → `funifier_logs type=trigger`
+- Para cada trigger: `name`, `_id`, `entity`, `event`, `status`.
+- Quais condições e quais ações executa (resumo do script Groovy)?
+- Está ativo? Tem logs de execução recentes? → silêncio = `CONCERNS.md`
+
+## Schedulers → `SCHEDULERS.md`
+
+`funifier_list type=scheduler` → `funifier_get mode=read` → `funifier_logs type=scheduler`
+- Para cada scheduler: `name`, `_id`, expressão `cron`, `active`/`status`.
+- Qual ação executa? Última execução conhecida (via logs)?
+- Está `active: false` mas parece importante? → `CONCERNS.md` + `[ASK USER]`
+
+## Custom endpoints → `CUSTOM_ENDPOINTS.md`
+
+`funifier_list type=public-endpoint` → `funifier_get mode=read`
+- Para cada endpoint: rota, método, parâmetros esperados, descrição, status.
+- Algum endpoint não é chamado por nenhum scheduler/trigger/página? → `CONCERNS.md`
+
+## Custom pages e widgets → `CUSTOM_PAGES.md`
+
+`funifier_list type=custom-page` e `type=widget`
+- Para cada um: `title`, rota, propósito, integrações (quais endpoints/aggregates consome).
+
+## Leaderboards → `LEADERBOARDS.md`
+
+`funifier_list type=leaderboard` → `funifier_get mode=read`
+- Para cada ranking: nome, métrica base (qual `point`/action/atributo), escopo (global/segmentado), período, regra de empate.
+
+## Modelo de player → `PLAYER_MODEL.md`
+
+`funifier_database action=query collection=player limit=3` (amostra) + `funifier_list type=auth-module`
+- Quais atributos custom aparecem nos documentos de player (campos além dos padrão)?
+- Há segmentações (`team`, hierarquia, extras)? Amostre `collection=team`.
+- Quais auth modules estão configurados?
+
+## Integrações → `INTEGRATIONS.md`
+
+`funifier_list type=websocket`, `type=ai-knowledge` + `funifier_database action=collections`
+- Há websockets configurados? Para quê?
+- Existe coleção de webhook/notification? Quais destinos externos?
+- Há triggers cujo script chama URLs externas? (descoberto no detalhamento)
+- Auth/integração externa configurada? → muitos itens aqui serão `[TODO]`/`[ASK USER]`.
+
+## Cobertura final
+
+Antes de sair da Fase 2, confirme que rodou `funifier_list` para **todos os 18 tipos** e `funifier_database action=collections` ao menos uma vez. Qualquer tipo com zero resultados deve ser registrado no `OVERVIEW.md` como contagem 0 (não omitido).

package/skills/acquire-funifier-knowledge/references/game-techniques-taxonomy.md

@@ -0,0 +1,62 @@
+# Taxonomia de técnicas de jogos
+
+Use na Fase 5 para classificar as técnicas observadas com vocabulário consistente. **Regra de ouro:** uma técnica só pode ser afirmada se houver um ou mais objetos Funifier concretos que a implementem. Para cada técnica que você reportar em `TECHNIQUES_AND_PATTERNS.md`, liste os IDs que a sustentam. Se não há objeto, a técnica não está presente — não a invente.
+
+## Como classificar
+
+Para cada técnica abaixo, pergunte: "Quais objetos mapeados (com ID) implementam isto?" Se a resposta for vazia, marque a técnica como **ausente** (ou omita). Se houver evidência parcial, marque `[ASK USER]` para confirmar a intenção.
+
+## Catálogo de técnicas
+
+### Loops de feedback (feedback loops)
+Resposta imediata a uma ação do jogador.
+- **Evidência típica:** `trigger` que credita `point` ao registrar uma `action`; notificações `on_win`; widgets de status que atualizam.
+- **Sinal de ausência:** actions registradas sem nenhum trigger/point reagindo.
+
+### Progressão (progression)
+Senso de avanço ao longo do tempo.
+- **Evidência típica:** `level` com `minPoints` crescentes; learning trail (folder) com desbloqueio condicional; cadeias de `challenge`.
+
+### Competição (competition)
+Comparação de desempenho entre jogadores.
+- **Evidência típica:** `leaderboard` (global ou segmentado); competições com prêmio por posição; ranking por `team`.
+
+### Colaboração (collaboration)
+Objetivos coletivos.
+- **Evidência típica:** `team`/grupos no modelo de player; challenges com `limitPerType=team`; leaderboards de time.
+
+### Recompensas e economia (rewards & economy)
+Incentivos tangíveis e moeda interna.
+- **Evidência típica:** `point` resgatável; `virtual-good-catalog`/`virtual-good-item`; mecânicas de troca/loja.
+
+### Conquistas e status (achievement & status)
+Marcos simbólicos.
+- **Evidência típica:** `challenge` de conclusão única; itens-badge no catálogo; títulos por nível.
+
+### Escassez e urgência (scarcity & urgency)
+Tempo ou quantidade limitados.
+- **Evidência típica:** challenges com janela de tempo (`limitTimeScale`); competições com data de fim; `scheduler` que abre/fecha temporadas.
+
+### Surpresa e sorte (surprise & chance)
+Recompensa aleatória.
+- **Evidência típica:** mystery box / sorteios (descobertos via `funifier_database`, fora do enum de `funifier_list`).
+
+### Narrativa (narrative)
+Contexto de história que dá sentido às ações.
+- **Evidência típica:** interactive story; nomenclatura temática de challenges/folders; conteúdo de páginas custom.
+
+### Onboarding e tutorial
+Condução dos primeiros passos.
+- **Evidência típica:** trigger no evento de cadastro/primeiro login; primeira etapa de uma learning trail; challenge introdutório.
+
+## Bloco de evidência por técnica
+
+Em `TECHNIQUES_AND_PATTERNS.md`, formate cada técnica assim:
+
+```
+### Progressão
+Presente. Implementada por:
+- Níveis L1–L5 (level _id: lvl_01..lvl_05), atrelados à categoria de ponto "xp" (point _id: pts_xp).
+- Trilha "Onboarding" (folder root: fld_onboarding) com desbloqueio sequencial.
+Evidence: funifier_list type=level; funifier_get type=point id=pts_xp; funifier_folder operation=inside folder=fld_onboarding
+```

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.