funifier-mcp 0.2.26 → 0.2.28

package/.cursor/rules/funifier.mdc

@@ -10,28 +10,6 @@ alwaysApply: true
 
 # Funifier Development Rules
 
-## Code Quality Persona
-
-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.
-
----
-
 ## Funifier Documentation
 
 Source of truth: `datasource-funifier-docs/`
@@ -44,30 +22,49 @@ npx funifier-mcp search "<query>" --top 5 --min-score 0.3
 
 ## Skill Workflows
 
-| Skill | When to use |
-|-------|-------------|
-| `/funifier-create-trigger` | Create a Funifier trigger — guided workflow from entity/event selection to Groovy code generation |
-| `/funifier-create-scheduler` | Create a Funifier scheduler — guided workflow from naming and cron expression to Groovy code generation |
-| `/funifier-create-aggregate` | Create a Funifier prepared aggregate — guided workflow for building MongoDB aggregate pipelines for reports and dashboards |
-| `/funifier-create-challenge` | Create a Funifier challenge — missions with action rules and point rewards |
-| `/funifier-create-action` | Create a Funifier action — define trackable player behaviors with attributes |
-| `/funifier-create-point` | Create a Funifier point category — XP, coins, or custom metrics |
-| `/funifier-create-level` | Create Funifier levels — progression system based on accumulated points |
-| `/funifier-create-leaderboard` | Create a Funifier leaderboard — rankings by points, actions, or attributes |
-| `/funifier-create-quiz` | Create a Funifier quiz — questionnaires with multiple-choice questions |
-| `/funifier-create-virtual-good` | Create a Funifier virtual good — catalog items players can purchase with points |
-| `/funifier-create-custom-page` | Create a Funifier Studio custom page — guided workflow for building admin dashboards, CRUDs, reports, and KPI pages using AngularJS + Bootstrap |
-| `/funifier-implement-frontend` | Implement frontend code that consumes the Funifier API — authentication, data fetching, and aggregate consumption |
-| `/funifier-debug` | Debug a Funifier resource — systematic diagnosis of triggers, schedulers, aggregates, and other Funifier components |
-| `/funifier-help` | Get help with Funifier — routes to the right documentation or skill based on your question |
-
-Full workflow files: `skills/<skill-id>/SKILL.md`
+| Reference | When to use |
+|-----------|-------------|
+| `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/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 |
+| `skills/funifier/references/create-point.md` | Create a Funifier point category — XP, coins, or custom metrics |
+| `skills/funifier/references/create-level.md` | Create Funifier levels — progression system based on accumulated points |
+| `skills/funifier/references/create-leaderboard.md` | Create a Funifier leaderboard — rankings by points, actions, or attributes |
+| `skills/funifier/references/create-quiz.md` | Create a Funifier quiz — questionnaires with multiple-choice questions |
+| `skills/funifier/references/create-virtual-good.md` | Create a Funifier virtual good — catalog items players can purchase with points |
+| `skills/funifier/references/create-custom-page.md` | Create a Funifier Studio custom page — guided workflow for building admin dashboards, CRUDs, reports, and KPI pages using AngularJS + Bootstrap |
+| `skills/funifier/references/implement-frontend.md` | Implement frontend code that consumes the Funifier API — authentication, data fetching, aggregate consumption, and static hosting on Funifier subdomain |
+| `skills/funifier/references/debug.md` | Debug a Funifier resource — systematic diagnosis of triggers, schedulers, aggregates, and other Funifier components |
+| `skills/funifier/references/help.md` | Get help with Funifier — routes to the right documentation or skill based on your question |
+| `skills/funifier/references/manage-player.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 |
+| `skills/funifier/references/manage-team.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 |
+| `skills/funifier/references/create-competition.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 |
+| `skills/funifier/references/create-folder.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 |
+| `skills/funifier/references/create-lottery.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) |
+| `skills/funifier/references/create-mystery.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) |
+| `skills/funifier/references/create-story.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 |
+| `skills/funifier/references/create-crossword.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 |
+| `skills/funifier/references/create-notification.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 |
+| `skills/funifier/references/create-lastmile.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 |
+| `skills/funifier/references/create-webhook.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) |
+| `skills/funifier/references/create-websocket.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) |
+| `skills/funifier/references/create-widget.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 |
+| `skills/funifier/references/create-swap.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 |
+| `skills/funifier/references/create-custom-object.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 |
+| `skills/funifier/references/configure-security.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) |
+| `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) |
+
+Full workflow files: `skills/funifier/references/`
 
 ### Funifier 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 |
@@ -86,7 +83,7 @@ Configure in `.mcp.json` — see `README.md`. Tools: `funifier_list` (always fil
 
 ## Rules
 
-- **Before any `funifier_*` MCP tool call**, check the Skill Workflows table above — if a skill matches, read its `SKILL.md` first. Skills contain correct enum values, field references, and examples.
+- **Before any `funifier_*` MCP tool call**, check the Skill Workflows table above — if a row matches, read the reference file listed. Reference files contain correct enum values, field references, and examples.
 - Search docs with `funifier-mcp search` before loading any file.
 - Groovy scripts in Funifier: no `import` statements, use `manager` object for all platform APIs.
 - Rebuild skills after doc changes: `npm run build:skills`.

package/.github/copilot-instructions.md

@@ -1,27 +1,5 @@
 # Copilot Instructions — Funifier Project
 
-## Code Quality Persona
-
-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.
-
----
-
 ## Project: Funifier Gamification Platform
 
 Documentation source of truth: `datasource-funifier-docs/`
@@ -34,30 +12,49 @@ npx funifier-mcp search "<query>" --top 5 --min-score 0.3
 
 ### Skill workflows
 
-Detailed guided workflows live in `skills/<skill-id>/SKILL.md`:
-
-| Skill | When to use |
-|-------|-------------|
-| `/funifier-create-trigger` | Create a Funifier trigger — guided workflow from entity/event selection to Groovy code generation |
-| `/funifier-create-scheduler` | Create a Funifier scheduler — guided workflow from naming and cron expression to Groovy code generation |
-| `/funifier-create-aggregate` | Create a Funifier prepared aggregate — guided workflow for building MongoDB aggregate pipelines for reports and dashboards |
-| `/funifier-create-challenge` | Create a Funifier challenge — missions with action rules and point rewards |
-| `/funifier-create-action` | Create a Funifier action — define trackable player behaviors with attributes |
-| `/funifier-create-point` | Create a Funifier point category — XP, coins, or custom metrics |
-| `/funifier-create-level` | Create Funifier levels — progression system based on accumulated points |
-| `/funifier-create-leaderboard` | Create a Funifier leaderboard — rankings by points, actions, or attributes |
-| `/funifier-create-quiz` | Create a Funifier quiz — questionnaires with multiple-choice questions |
-| `/funifier-create-virtual-good` | Create a Funifier virtual good — catalog items players can purchase with points |
-| `/funifier-create-custom-page` | Create a Funifier Studio custom page — guided workflow for building admin dashboards, CRUDs, reports, and KPI pages using AngularJS + Bootstrap |
-| `/funifier-implement-frontend` | Implement frontend code that consumes the Funifier API — authentication, data fetching, and aggregate consumption |
-| `/funifier-debug` | Debug a Funifier resource — systematic diagnosis of triggers, schedulers, aggregates, and other Funifier components |
-| `/funifier-help` | Get help with Funifier — routes to the right documentation or skill based on your question |
+Detailed guided workflows live in `skills/funifier/references/`:
+
+| Reference | When to use |
+|-----------|-------------|
+| `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/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 |
+| `skills/funifier/references/create-point.md` | Create a Funifier point category — XP, coins, or custom metrics |
+| `skills/funifier/references/create-level.md` | Create Funifier levels — progression system based on accumulated points |
+| `skills/funifier/references/create-leaderboard.md` | Create a Funifier leaderboard — rankings by points, actions, or attributes |
+| `skills/funifier/references/create-quiz.md` | Create a Funifier quiz — questionnaires with multiple-choice questions |
+| `skills/funifier/references/create-virtual-good.md` | Create a Funifier virtual good — catalog items players can purchase with points |
+| `skills/funifier/references/create-custom-page.md` | Create a Funifier Studio custom page — guided workflow for building admin dashboards, CRUDs, reports, and KPI pages using AngularJS + Bootstrap |
+| `skills/funifier/references/implement-frontend.md` | Implement frontend code that consumes the Funifier API — authentication, data fetching, aggregate consumption, and static hosting on Funifier subdomain |
+| `skills/funifier/references/debug.md` | Debug a Funifier resource — systematic diagnosis of triggers, schedulers, aggregates, and other Funifier components |
+| `skills/funifier/references/help.md` | Get help with Funifier — routes to the right documentation or skill based on your question |
+| `skills/funifier/references/manage-player.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 |
+| `skills/funifier/references/manage-team.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 |
+| `skills/funifier/references/create-competition.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 |
+| `skills/funifier/references/create-folder.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 |
+| `skills/funifier/references/create-lottery.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) |
+| `skills/funifier/references/create-mystery.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) |
+| `skills/funifier/references/create-story.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 |
+| `skills/funifier/references/create-crossword.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 |
+| `skills/funifier/references/create-notification.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 |
+| `skills/funifier/references/create-lastmile.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 |
+| `skills/funifier/references/create-webhook.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) |
+| `skills/funifier/references/create-websocket.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) |
+| `skills/funifier/references/create-widget.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 |
+| `skills/funifier/references/create-swap.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 |
+| `skills/funifier/references/create-custom-object.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 |
+| `skills/funifier/references/configure-security.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) |
+| `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) |
 
 ### Funifier 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 |
@@ -77,7 +74,7 @@ See `README.md` for MCP configuration.
 
 ### Key rules
 
-- **Before any `funifier_*` MCP tool call**, check the Skill Workflows table above — if a skill matches, follow it. Skills contain correct enum values, field references, and examples that prevent common errors.
+- **Before any `funifier_*` MCP tool call**, check the Skill Workflows table above — if a row matches, read the reference file listed. Reference files contain correct enum values, field references, and examples that prevent common errors.
 - Always search docs before reading them in full.
 - Never assume patterns from existing live resources — use `datasource-funifier-docs/` as source of truth.
 - Funifier server-side scripts run in **Groovy** (Java-compatible). No `import` statements — all classes are pre-loaded.

package/AGENTS.md

@@ -1,44 +1,34 @@
 # Funifier Agent Instructions
 
-## 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:
+## Funifier Platform
 
-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)**
+This project uses [Funifier](https://funifier.com), a gamification platform. Documentation lives in `datasource-funifier-docs/`.
 
-Só então prossiga com a implementação.
+<!-- funifier-persona:start -->
+## Persona e Qualidade de Código
 
-> **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.
+Atue como um **desenvolvedor de software sênior**, especializado em **código limpo, legível e de fácil manutenção**, seguindo boas práticas da indústria e **evitando overengineering**.
 
----
+Ao refatorar ou criar código:
 
-## Funifier Platform
+1. Analise o problema ou o código existente.
+2. Raciocine passo a passo antes de escrever qualquer linha.
+3. Identifique problemas (refatoração) ou requisitos (código novo).
+4. Defina prioridades com base em **SOLID**, **DRY**, **KISS** e **YAGNI**.
+5. Justifique tecnicamente cada decisão.
 
-This project uses [Funifier](https://funifier.com), a gamification platform.
-All Funifier documentation lives in `datasource-funifier-docs/`.
+> **IMPORTANTE:** os exemplos da documentação Funifier são ilustrativos — podem usar nomes genéricos ou scripts monolíticos. Sempre melhore-os: use nomes descritivos, extraia métodos especializados e mantenha cada função com responsabilidade única.
+<!-- funifier-persona:end -->
 
-### Finding relevant documentation
+## Finding documentation
 
-Use the lexical search CLI to find the most relevant files before reading them:
+Search before reading — load only the top results, never all docs at once:
 
 ```bash
-npx funifier-mcp search "<your question or task>"
-npx funifier-mcp search "<query>" --skill <skill-id> --top 5 --min-score 0.3
+npx funifier-mcp search "<query>" --top 5 --min-score 0.3
 ```
 
-Only read files returned with score above the threshold. Avoid loading all docs at once.
-
-### MCP Tools (if MCP server is running)
+## MCP Tools (if MCP server is running)
 
 | Tool | Description |
 |------|-------------|
@@ -53,32 +43,51 @@ Only read files returned with score above the threshold. Avoid loading all docs
 
 MCP setup: see `README.md` → "MCP Server Setup".
 
-### Skill Routing
-
-| Skill | When to use |
-|-------|-------------|
-| `/funifier-create-trigger` | Create a Funifier trigger — guided workflow from entity/event selection to Groovy code generation |
-| `/funifier-create-scheduler` | Create a Funifier scheduler — guided workflow from naming and cron expression to Groovy code generation |
-| `/funifier-create-aggregate` | Create a Funifier prepared aggregate — guided workflow for building MongoDB aggregate pipelines for reports and dashboards |
-| `/funifier-create-challenge` | Create a Funifier challenge — missions with action rules and point rewards |
-| `/funifier-create-action` | Create a Funifier action — define trackable player behaviors with attributes |
-| `/funifier-create-point` | Create a Funifier point category — XP, coins, or custom metrics |
-| `/funifier-create-level` | Create Funifier levels — progression system based on accumulated points |
-| `/funifier-create-leaderboard` | Create a Funifier leaderboard — rankings by points, actions, or attributes |
-| `/funifier-create-quiz` | Create a Funifier quiz — questionnaires with multiple-choice questions |
-| `/funifier-create-virtual-good` | Create a Funifier virtual good — catalog items players can purchase with points |
-| `/funifier-create-custom-page` | Create a Funifier Studio custom page — guided workflow for building admin dashboards, CRUDs, reports, and KPI pages using AngularJS + Bootstrap |
-| `/funifier-implement-frontend` | Implement frontend code that consumes the Funifier API — authentication, data fetching, and aggregate consumption |
-| `/funifier-debug` | Debug a Funifier resource — systematic diagnosis of triggers, schedulers, aggregates, and other Funifier components |
-| `/funifier-help` | Get help with Funifier — routes to the right documentation or skill based on your question |
-
-To get detailed workflow guidance for any skill, read the corresponding `skills/<skill-id>/SKILL.md`.
+## Skill Routing
+
+Before any `funifier_*` MCP tool call or Funifier task, find the matching row and **read the referenced file** — it carries the correct enum values, field references, and examples that prevent common errors.
+
+| Reference | When to use |
+|-----------|-------------|
+| `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/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 |
+| `skills/funifier/references/create-point.md` | Create a Funifier point category — XP, coins, or custom metrics |
+| `skills/funifier/references/create-level.md` | Create Funifier levels — progression system based on accumulated points |
+| `skills/funifier/references/create-leaderboard.md` | Create a Funifier leaderboard — rankings by points, actions, or attributes |
+| `skills/funifier/references/create-quiz.md` | Create a Funifier quiz — questionnaires with multiple-choice questions |
+| `skills/funifier/references/create-virtual-good.md` | Create a Funifier virtual good — catalog items players can purchase with points |
+| `skills/funifier/references/create-custom-page.md` | Create a Funifier Studio custom page — guided workflow for building admin dashboards, CRUDs, reports, and KPI pages using AngularJS + Bootstrap |
+| `skills/funifier/references/implement-frontend.md` | Implement frontend code that consumes the Funifier API — authentication, data fetching, aggregate consumption, and static hosting on Funifier subdomain |
+| `skills/funifier/references/debug.md` | Debug a Funifier resource — systematic diagnosis of triggers, schedulers, aggregates, and other Funifier components |
+| `skills/funifier/references/help.md` | Get help with Funifier — routes to the right documentation or skill based on your question |
+| `skills/funifier/references/manage-player.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 |
+| `skills/funifier/references/manage-team.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 |
+| `skills/funifier/references/create-competition.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 |
+| `skills/funifier/references/create-folder.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 |
+| `skills/funifier/references/create-lottery.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) |
+| `skills/funifier/references/create-mystery.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) |
+| `skills/funifier/references/create-story.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 |
+| `skills/funifier/references/create-crossword.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 |
+| `skills/funifier/references/create-notification.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 |
+| `skills/funifier/references/create-lastmile.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 |
+| `skills/funifier/references/create-webhook.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) |
+| `skills/funifier/references/create-websocket.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) |
+| `skills/funifier/references/create-widget.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 |
+| `skills/funifier/references/create-swap.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 |
+| `skills/funifier/references/create-custom-object.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 |
+| `skills/funifier/references/configure-security.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) |
+| `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) |
 
 ## Funifier 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 |
@@ -91,8 +100,6 @@ To get detailed workflow guidance for any skill, read the corresponding `skills/
 
 ## Key Rules
 
-- **Before any `funifier_*` MCP tool call**, check the Skill Routing table above — if a skill matches, follow it. Skills contain correct enum values, field references, and examples that prevent common errors.
-- **Search before reading**: always run `funifier-mcp search` first, then read only the top results.
 - **Never list all MCP resources** without a `search` parameter — always filter.
 - **Docs are authoritative for patterns**: never infer patterns from existing live resources.
 - **Run `npm run build:skills`** after editing any file in `datasource-funifier-docs/`.

package/README.md

@@ -8,7 +8,7 @@ Funifier AI toolkit — API client, MCP server, and AI assistant skills for the
 |-----------|-------------|
 | **API Client** | Pure Node.js client for the Funifier REST API (80+ methods, 18 resource types) |
 | **MCP Server** | Model Context Protocol server — 8 tools, 3 prompts, documentation resources |
-| **Skills** | 15 guided workflows for Claude Code, Codex, OpenCode, Copilot, Continue, and Cursor |
+| **Skills** | 32 guided workflows for Claude Code, Codex, OpenCode, Copilot, Continue, and Cursor |
 | **CLI** | `npx funifier-mcp@latest init` (interactive setup) and `npx funifier-mcp search` (doc search) |
 
 ---
@@ -38,7 +38,7 @@ Lexical search across all Funifier docs — returns ranked file paths so you onl
 
 ```bash
 npx funifier-mcp search "trigger event groovy before_create"
-npx funifier-mcp search "quiz question answer" --skill funifier-create-quiz
+npx funifier-mcp search "quiz question answer"
 npx funifier-mcp search "leaderboard ranking" --top 5 --min-score 0.3
 ```
 
@@ -152,12 +152,10 @@ npm install funifier-mcp
 cp -r node_modules/funifier-mcp/skills/* .claude/skills/
 ```
 
-Invoke any skill with `/funifier-<name>` in Claude Code:
+Start with `/funifier` in Claude Code — the router skill routes to the right workflow:
 
 ```
-/funifier-create-trigger
-/funifier-debug
-/funifier-help
+/funifier
 ```
 
 ### Codex CLI / OpenCode
@@ -193,22 +191,42 @@ Cursor discovers and applies `.mdc` files in `.cursor/rules/` automatically.
 
 ## Available Workflows
 
-| Skill | Description |
-|-------|-------------|
-| `funifier-help` | Documentation router and guidance |
-| `funifier-debug` | Systematic debugging workflow |
-| `funifier-create-trigger` | Create server-side event handlers (Groovy) |
-| `funifier-create-scheduler` | Create scheduled Groovy jobs |
-| `funifier-create-aggregate` | Create MongoDB aggregate pipelines |
-| `funifier-create-custom-page` | Create Studio admin pages (AngularJS) |
-| `funifier-create-action` | Create trackable player actions |
-| `funifier-create-challenge` | Create missions with rewards |
-| `funifier-create-point` | Create point categories |
-| `funifier-create-level` | Create level progression |
-| `funifier-create-leaderboard` | Create rankings |
-| `funifier-create-quiz` | Create quizzes |
-| `funifier-create-virtual-good` | Create virtual store items |
-| `funifier-implement-frontend` | Build frontend consuming Funifier API |
+All workflows are accessible through a single `/funifier` skill. The skill router loads in every conversation (one description) and loads the specific workflow file on demand.
+
+| Workflow | Reference file |
+|----------|----------------|
+| Help and routing | `references/help.md` |
+| Debug any resource | `references/debug.md` |
+| Create trigger | `references/create-trigger.md` |
+| Create scheduler | `references/create-scheduler.md` |
+| Create aggregate | `references/create-aggregate.md` |
+| Create custom page | `references/create-custom-page.md` |
+| Create action | `references/create-action.md` |
+| Create challenge | `references/create-challenge.md` |
+| Create point category | `references/create-point.md` |
+| Create level progression | `references/create-level.md` |
+| Create leaderboard | `references/create-leaderboard.md` |
+| Create quiz | `references/create-quiz.md` |
+| Create virtual good | `references/create-virtual-good.md` |
+| Implement frontend | `references/implement-frontend.md` |
+| Manage player | `references/manage-player.md` |
+| Manage team | `references/manage-team.md` |
+| Create competition | `references/create-competition.md` |
+| Create folder | `references/create-folder.md` |
+| Create lottery | `references/create-lottery.md` |
+| Create mystery box | `references/create-mystery.md` |
+| Create story | `references/create-story.md` |
+| Create crossword | `references/create-crossword.md` |
+| Create notification | `references/create-notification.md` |
+| Create last mile | `references/create-lastmile.md` |
+| Create webhook | `references/create-webhook.md` |
+| Create websocket | `references/create-websocket.md` |
+| Create widget | `references/create-widget.md` |
+| Create swap | `references/create-swap.md` |
+| Create custom object | `references/create-custom-object.md` |
+| Configure security | `references/configure-security.md` |
+| Import CSV | `references/import-csv.md` |
+| Upload file | `references/upload-file.md` |
 
 ---