funifier-mcp 0.2.26 → 0.2.27

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

@@ -0,0 +1,98 @@
+# funifier-create-competition
+
+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
+
+---
+
+## Before starting — find relevant docs
+
+Run lexical search to load only what you need:
+
+```bash
+npx funifier-mcp search "competition contest ranking tournament enrollment rewards position gt26" --skill funifier-create-competition
+```
+
+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/competition.md`
+
+## Steps
+
+### Rules — follow exactly, no exceptions
+
+**Technique:** always `["GT26"]`.
+**`operation.type`:**
+- `1` = Count actions
+- `3` = Sum achievements (points) — most common
+
+**`period.expression`:** Funifier date syntax, e.g. `"-0M-;+1M+"` = current month.
+**Rewards by position:** use `extra.position_start` and `extra.position_ends` on each reward.
+**Execution:** automatic (`autoExecute: true`) or manual (`GET /v3/competition/:id/execute`).
+
+---
+
+### 1. Check dependencies
+
+```
+funifier_list type=point search=<metric>
+funifier_list type=action search=<metric>
+```
+
+### 2. Check if competition already exists
+
+```
+funifier_list type=competition search=<title>
+```
+
+### 3. Build the payload
+
+```json
+{
+  "title": "Sales Race",
+  "description": "Top sellers of the month",
+  "period": { "expression": "-0M-;+1M+" },
+  "maxWinners": 3,
+  "maxPlayers": 100,
+  "minScore": 0,
+  "operation": {
+    "type": 3,
+    "achievement_type": 0,
+    "item": "xp",
+    "sort": -1,
+    "sub": false,
+    "filters": []
+  },
+  "rewards": [
+    { "total": 200, "type": 0, "item": "xp", "operation": 0, "extra": { "position_start": 1, "position_ends": 1 }, "restrict": false, "perPlayer": false },
+    { "total": 100, "type": 0, "item": "xp", "operation": 0, "extra": { "position_start": 2, "position_ends": 3 }, "restrict": false, "perPlayer": false }
+  ],
+  "notifications": [],
+  "active": true,
+  "teamCompetition": false,
+  "autoExecute": true,
+  "techniques": ["GT26"]
+}
+```
+
+### 4. Save
+
+```
+funifier_save type=competition payload=<json>
+```
+
+### 5. Enroll players
+
+```
+POST /v3/competition/join   { "competition": "<_id>", "player": "<player_id>" }
+```
+
+### 6. Check leaderboard and execute
+
+```
+POST /v3/competition/leader/aggregate?id=<_id>
+GET /v3/competition/<_id>/execute   (manual execution only)
+```

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

@@ -0,0 +1,574 @@
+# funifier-create-crossword
+
+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
+
+---
+
+## Documentação do módulo (já incluída — não precisa buscar)
+
+**Acesso Studio:** Não há módulo Studio dedicado a `crossword`. Nenhuma rota `/studio/crossword` existe no código. O objeto gerado é, tipicamente, persistido/exibido pelo **chamador** (frontend / Studio) como parte de outro recurso — o backend não oferece tela nem CRUD próprios.
+**API Endpoint:** `POST /v3/ai/build/crossword` — **único** endpoint. Classe `com.funifier.rest.v3.rest.AIRest` (`@Path("v3/ai")`), método `buildCrossword` (`@Path("/build/crossword")`, `AIRest.java:1861-1994`).
+**Coleção MongoDB:** **Nenhuma.** O crossword é gerado em runtime e devolvido ao chamador; **não é persistido** pelo backend. Único side effect de escrita: na primeira chamada, o prompt `intro_build_crossword` é inserido em `Entity.AI_PROMPT.collection` (coleção de prompts da IA, global ao tenant) — **não** em uma coleção `crossword`.
+
+---
+
+## 1. Visão Geral
+
+> **Aviso de engenharia reversa.** A documentação anterior descrevia um módulo CRUD `/v3/crossword` com tela `/studio/crossword` e coleção MongoDB `crossword`. **Nada disso existe no código.** Verificação por busca em `funifier-service/src/main/java` (`grep -rn "/crossword\|\"crossword\""`) não retorna nenhuma rota `/v3/crossword` nem mapeamento de coleção fora do pacote `engine/crossword` e de `AIRest`. O conteúdo abaixo reflete **exclusivamente** o comportamento real.
+
+O `crossword` na plataforma Funifier é composto por **duas peças**, sem relação CRUD entre si:
+
+1. **Motor de layout em memória** — pacote `com.funifier.engine.crossword`. Recebe um conjunto de palavras e produz um tabuleiro de palavras cruzadas posicionando-as com cruzamentos (interseções de letras). É um gerador algorítmico de quebra-cabeça, sem persistência.
+2. **Endpoint de IA** — `POST /v3/ai/build/crossword` em `AIRest`. Pede ao ChatGPT que gere palavras + dicas a partir de um tema em linguagem natural, executa o motor de layout sobre essas palavras e devolve o JSON do crossword montado.
+
+Papel arquitetural:
+
+- É **um entre ~30 geradores de IA** expostos por `AIRest` (`/build/quiz`, `/build/level`, `/build/challenge`, `/build/lottery`, `/build/mystery`, etc.). Todos seguem o mesmo padrão: prompt introdutório + function calling do OpenAI → POJO da plataforma.
+- O crossword produzido é um **artefato transiente**: o backend o devolve e esquece. Cabe ao chamador decidir se salva (por exemplo, embutindo-o no `extra` de um `challenge` ou em um `database`/`custom_object`).
+
+Dependências em runtime:
+
+- `com.funifier.engine.system.ai` — `Prompt`, `AIManager` (`findPrompt`/`insertPrompt`), `ChatCompletionRequest`/`ChatCompletionResult`.
+- API externa **OpenAI** (`https://api.openai.com/v1/chat/completions`, modelo `gpt-3.5-turbo-1106`).
+- `com.funifier.engine.guid.Guid` — geração do `_id`.
+
+Não há, em runtime, acoplamento com `challenge`, `player`, `achievement` ou qualquer outro módulo de gamificação.
+
+---
+
+## 2. Arquitetura e Fluxos
+
+### 2.1 Classes envolvidas
+
+| Classe | Papel |
+|---|---|
+| `rest.v3.rest.AIRest.buildCrossword` | Entrada REST (`POST /v3/ai/build/crossword`). Orquestra ChatGPT + motor de layout |
+| `engine.crossword.Crossword` | POJO de saída (documento raiz) + factory estática `create(...)` |
+| `engine.crossword.Word` | Sub-objeto de saída — uma palavra posicionada |
+| `engine.crossword.CrossBoard` | Motor de layout. Tabuleiro `Cell[60][60]`, posicionamento e ajuste |
+| `engine.crossword.Checks` | Validação de posições candidatas (cruzamentos, limites, adjacências) |
+| `engine.crossword.Coordinate` | Posição candidata `{x, y, isVertical}` |
+| `engine.crossword.AddedWord` | Palavra já posicionada `{posicaoX, posicaoY, palavra, isVertical, casas[], isPrincipal}` |
+| `engine.crossword.Cell` | Célula do tabuleiro `{letra, isOcupada, isInativa, isPrincipal}` |
+| `engine.crossword.WordComparator` | `Comparator<String>` — ordena por **comprimento decrescente** |
+| `engine.crossword.Utility` | Utilitários **legados** (carregar palavras de arquivo, gerar DOCX). **Não usados** no fluxo de IA |
+| `engine.crossword.WordList` | Agrupamento de palavras por tamanho — usado **apenas** pela geração DOCX legada |
+| `engine.crossword.CrosswordTest` | Classe de teste/`main` standalone |
+
+Não há `Resource` CRUD, `Service`, `Repository`/`Dao`, `Manager` nem `Scheduler`/`Job` para crossword. A única "porta" é o método `buildCrossword`.
+
+### 2.2 Pipeline principal — `buildCrossword` (`AIRest.java:1861`)
+
+Fluxo **síncrono** (bloqueia na chamada HTTP ao OpenAI via Unirest). Sem transação, sem persistência do resultado.
+
+```
+[1] Lê do body:  content (String, prompt do usuário)  e  current (Object, opcional)
+[2] intro = IAManager.findPrompt("intro_build_crossword")
+    SE intro == null:
+        intro = new Prompt("intro_build_crossword", ..., <instrução hardcoded>)
+        IAManager.insertPrompt(intro)        // SIDE EFFECT: grava em AI_PROMPT (global)
+[3] Define a function OpenAI "build_crossword" (param obrigatório: crossword: string)
+    Monta system message "formatacao" instruindo o modelo a chamar a function
+[4] ChatCompletionRequest:
+        model   = gpt-3.5-turbo-1106 (MODEL_GPT_3_5)
+        system  = intro.content
+        system  = "Este é o crossword atual do usuário: ..." (SOMENTE se current != null)
+        system  = formatacao
+        user    = content
+        function_call = "auto"
+[5] POST https://api.openai.com/v1/chat/completions
+        header Authorization = CHATGPT_TOKEN  (TOKEN HARDCODED — AIRest.java:79 — ver §8)
+[6] result = parse(response);  call = result.choices[0].message.functionCall
+    json = call.getArguments()
+[7] p = fromJson(json)          // { "crossword": ... }
+    SE p.crossword é String  → p = parse(p.crossword)      // JSON aninhado em string
+    SENÃO                    → p = parse(toJson(p.crossword))
+[8] Extrai com try/catch silencioso (apenas printStackTrace em falha):
+        title       = String(p.title)
+        description = String(p.description)
+        select      = parseInt(p.select)        // default local = 5 se ausente/inválido
+        map         = fromJson(p.words)          // HashMap<palavra, dica>
+[9] crossword = Crossword.create(title, description, map, select)
+[10] return Callback 200 com toJson(crossword)
+```
+
+Observações:
+
+- A extração do passo [8] usa `try { ... } catch (Exception e) { e.printStackTrace(); }` para cada campo. Falha de parse **não** aborta a requisição — o campo simplesmente fica com o valor anterior (`null` / `5`). Ver modos de falha em §9.
+- O bloco inline comentado em `AIRest.java:1949-1991` é uma **duplicata** antiga da lógica de `Crossword.create` (com clamp `> 10 ? 10`). Foi substituído pela chamada a `Crossword.create` (linha 1992), que usa clamp `> 20 ? 20`. Ver §7.
+
+#### Fluxo — `buildCrossword`
+
+```mermaid
+flowchart TB
+    A[POST /v3/ai/build/crossword<br/>content, current] --> B{findPrompt<br/>intro_build_crossword}
+    B -- null --> C[insertPrompt em AI_PROMPT]
+    B -- existe --> D[Monta ChatCompletionRequest]
+    C --> D
+    D --> E[POST OpenAI chat/completions<br/>token hardcoded]
+    E --> F[functionCall.arguments]
+    F --> G[Extrai title, description,<br/>select, words map]
+    G --> H[Crossword.create]
+    H --> I[200 + JSON do crossword]
+```
+
+#### Interação com OpenAI
+
+```mermaid
+sequenceDiagram
+    participant Cli as Chamador
+    participant AI as AIRest.buildCrossword
+    participant Mgr as AIManager
+    participant GPT as OpenAI
+    participant Eng as Crossword.create / CrossBoard
+
+    Cli->>AI: POST /v3/ai/build/crossword {content, current?}
+    AI->>Mgr: findPrompt("intro_build_crossword")
+    alt prompt ausente
+        AI->>Mgr: insertPrompt(intro)  (AI_PROMPT)
+    end
+    AI->>GPT: chat/completions (function build_crossword)
+    GPT-->>AI: function_call.arguments (JSON: title, description, words, select)
+    AI->>Eng: create(title, description, words, select)
+    Eng-->>AI: Crossword {_id, title, description, words[]}
+    AI-->>Cli: 200 + JSON
+```
+
+### 2.3 Pipeline de layout — `Crossword.create` (`Crossword.java:32`)
+
+```
+[1] numTotalPalavras = (select < 1 || select > 20) ? 20 : select   // clamp [1,20], default 20
+[2] tabuleiro = new CrossBoard(60, numTotalPalavras, true)          // grid 60x60
+[3] adicionadas = tabuleiro.gerarPalavrasAdicionadas(words.keySet(), numTotalPalavras)
+[4] System.out de cada palavra adicionada + total                  // stdout
+[5] tabuleiro.ajustarTabuleiro()                                    // recorta bordas vazias
+[6] tabuleiro.imprimirTabuleiro()                                   // stdout
+[7] PARA i = 0..adicionadas.size()-1:
+        Word(
+          number    = i + 1,
+          direction = isVertical ? "vertical" : "horizontal",
+          row       = posicaoX + 1,        // 1-indexed
+          column    = posicaoY + 1,        // 1-indexed
+          hint      = words.get(palavra),  // dica pela chave exata
+          word      = palavra
+        )
+[8] Crossword.builder()._id(Guid.newShortGuid())                    // ObjectId hex, 24 chars
+        .title(title).description(description).words(words).build()
+```
+
+### 2.4 Posicionamento das palavras — `CrossBoard`
+
+`gerarPalavrasAdicionadas` (`CrossBoard.java:26`):
+
+```
+[1] gerarTabuleiroVazio()                                  // 60x60 Cells vazias
+[2] limpa faltam / adicionadas / puladas; palavrasJaTrocadas = false
+[3] faltam = cópia das palavras;  Collections.sort(faltam, WordComparator)  // maior → menor
+[4] posicionarPalavraInicial()
+[5] posicionarPalavras()
+[6] return adicionadas
+```
+
+`posicionarPalavraInicial` (`CrossBoard.java:112`):
+- `escolherUmaPalavra()` seleciona a primeira palavra.
+- SE comprimento > `tamanho` (60) → **retorna sem posicionar** (caso de borda).
+- Posiciona próximo ao **centro** com `Coordinate(x, y, isVertical=true)` — a palavra inicial é **vertical** (apesar do comentário "para ser horizontal...").
+- Marca `adicionadas.get(0).isPrincipal = true` (palavra "principal"; sem restrição de cruzamento).
+
+`escolherUmaPalavra` (`CrossBoard.java:128`):
+- SE `faltam.size() > 4` → índice aleatório em `[0, faltam.size()/2)` (favorece a metade mais longa).
+- SENÃO → `faltam.get(0)` (a mais longa restante).
+
+`posicionarPalavras` (`CrossBoard.java:179` — versão **ativa**):
+
+```
+isVertical = true
+maxTentativas = faltam.size() * 2
+ENQUANTO faltam não vazio E adicionadas.size() < numPalavras E tentativas < maxTentativas:
+    palavra    = escolherUmaPalavra()
+    isVertical = !isVertical                       // ALTERNA direção a cada iteração
+    adicionou  = tentarAdicionarPalavra(palavra, isVertical)
+    SE não adicionou:
+        atualizarListasFaltamParaPuladas(palavra)  // move de faltam → puladas
+        tentativas++
+    SENÃO:
+        tentativas = 0
+    SE puladas não vazio:
+        tentarPosicionarPuladas(isVertical)        // tenta reencaixar puladas
+```
+
+`verifDisponibilidade` (`Checks.java:13`) decide onde uma palavra pode entrar:
+
+```
+posicoes = contarPossiveisPosicoes(palavra, isVertical)
+    // para CADA palavra já adicionada, verifPalavra() acha cruzamentos
+    // SOMENTE perpendiculares (palavraAdicionada.isVertical != isVertical)
+    // onde uma letra coincide
+SE posicoes vazio → null
+posicoes = removerPosicoesInadequadas(posicoes, palavra)
+    // mantém só as que passam em:
+    //   verifLimites()          → cabe dentro do tabuleiro
+    //   verifCasasNoTabuleiro() → sem adjacência indevida; letras coincidem no cruzamento
+SE posicoes vazio → null
+SENÃO → posicoes[ Random.nextInt(posicoes.size()) ]   // escolha ALEATÓRIA
+```
+
+Consequência: a partir da segunda palavra, **só entram palavras que cruzam** uma palavra já posicionada compartilhando uma letra. Palavras sem cruzamento possível vão para `puladas` e podem nunca entrar.
+
+#### Loop de posicionamento
+
+```mermaid
+flowchart TB
+    S[faltam ordenado por tamanho] --> Ini[posicionarPalavraInicial<br/>vertical, centro, isPrincipal]
+    Ini --> L{"faltam vazio? OR<br/>adicionadas >= numPalavras? OR<br/>tentativas >= max?"}
+    L -- continuar --> P[escolherUmaPalavra]
+    P --> T[isVertical = !isVertical]
+    T --> V[verifDisponibilidade<br/>cruzamentos perpendiculares]
+    V -- posição válida --> Add[adicionarPalavraTabuleiro<br/>tentativas = 0]
+    V -- nenhuma --> Sk[move para puladas<br/>tentativas++]
+    Add --> R[tentarPosicionarPuladas]
+    Sk --> R
+    R --> L
+    L -- parar --> Fim[adicionadas]
+```
+
+`ajustarTabuleiro` (`CrossBoard.java:49`): calcula `minX/minY/maxX/maxY` das palavras adicionadas, desloca todas para a origem (`posicaoX -= minX`, `posicaoY -= minY`) e recalcula `tamanho`. É depois desse passo que `row = posicaoX + 1` e `column = posicaoY + 1` ficam relativos ao canto do tabuleiro recortado.
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 `Crossword` — documento raiz (saída)
+
+`com.funifier.engine.crossword.Crossword`. **Não persistido pelo backend** — é o corpo da resposta.
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | String | `Guid.newShortGuid()` | Não (auto) | Gerado por `new org.bson.types.ObjectId().toString()` → **hex de 24 caracteres**, apesar do tipo `String`. Mapeado por `@JsonProperty("_id")` |
+| `title` | String | `"null"` (string) se ausente | Não | Título vindo do JSON gerado pela IA. Se a IA omitir, `String.valueOf(p.get("title"))` produz a **string literal** `"null"` (não o valor nulo) — ver §9 |
+| `description` | String | `"null"` (string) se ausente | Não | Descrição vinda do JSON da IA. Mesmo efeito `"null"` literal se ausente |
+| `words` | List<`Word`> | `[]` | Sim (significativo) | Palavras efetivamente posicionadas no tabuleiro. **Tamanho ≤ `select`** (pode ser menor) |
+
+Anotações: `@Data @Builder(toBuilder=true) @NoArgsConstructor @AllArgsConstructor @JsonIgnoreProperties(ignoreUnknown=true)`. `words` é `@Singular`.
+
+**Campos computados / não persistidos:** todo o objeto é transiente — nada vai ao MongoDB por este fluxo.
+
+### 3.2 `Word` — sub-entidade (saída)
+
+`com.funifier.engine.crossword.Word`. Um item de `Crossword.words`.
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `number` | int | — | Sim | Sequencial `1..N` na ordem de adição ao tabuleiro (não é ordem de leitura/grade) |
+| `direction` | String | — | Sim | `"vertical"` ou `"horizontal"`. Derivado de `AddedWord.isVertical` |
+| `row` | int | — | Sim | `posicaoX + 1` — **1-indexed**. Eixo das linhas (cresce para baixo) |
+| `column` | int | — | Sim | `posicaoY + 1` — **1-indexed**. Eixo das colunas |
+| `hint` | String | — | Sim | Dica da palavra (`words.get(palavra)`, busca pela chave exata) |
+| `word` | String | — | Sim | A própria palavra |
+
+**Semântica de coordenadas:** `x` é a linha, `y` é a coluna. `isVertical == true` → a palavra se estende ao longo de `x` (linhas, de cima para baixo). `row`/`column` são **1-indexados** na resposta (o motor é 0-indexed internamente).
+
+### 3.3 Estruturas internas (não saem na resposta)
+
+| Classe | Campos | Observação |
+|---|---|---|
+| `Cell` | `letra` (char), `isOcupada` (bool), `isInativa` (bool), `isPrincipal` (bool) | `isInativa` é **lido** em `Checks.verifPalavra` mas **nunca escrito** em lugar nenhum → sempre `false` → ramo morto (ver §7) |
+| `AddedWord` | `posicaoX`, `posicaoY`, `palavra`, `isVertical`, `casas[]`, `isPrincipal` | `isPrincipal` marca a primeira palavra; **não** é exportado para `Word` |
+| `Coordinate` | `x`, `y`, `isVertical` | Posição candidata produzida por `Checks` |
+| `CrossBoard` | `tamanho`, `numPalavras`, `faltam`, `adicionadas`, `puladas`, `tabuleiro[][]`, ... | Estado do motor; descartado ao fim de `create` |
+
+### 3.4 Estrutura do JSON gerado pela IA (entrada do motor)
+
+O ChatGPT é instruído (prompt `intro_build_crossword`) a produzir um JSON com:
+
+| Campo | Tipo | Descrição (conforme o prompt) |
+|---|---|---|
+| `title` | String | Título do jogo |
+| `description` | String | Descrição |
+| `words` | Map<palavra, dica> | Pares palavra→dica. O prompt manda gerar **o dobro** das palavras pedidas, limitado a **40** |
+| `select` | int | Quantas palavras o usuário quer ver no jogo, limitado a **20** no prompt |
+
+Notas do prompt: as palavras devem ser **MAIÚSCULAS** por padrão (outro formato só se o usuário pedir). O pool maior (`words`) que `select` dá folga ao algoritmo para achar boas interseções.
+
+---
+
+## 4. Endpoints
+
+### 4.1 `POST /v3/ai/build/crossword`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Gerar um crossword (palavras + dicas + layout) a partir de um tema em linguagem natural, via IA |
+| Autenticação | Bearer token (`@BeanParam AuthBean`) |
+| Consumes | `application/json` |
+| Produces | `application/json; charset=UTF-8` |
+| Full replace ou patch | N/A — não é CRUD. Gera e devolve; **não persiste** |
+| Idempotência | **Não** — saída varia entre chamadas idênticas (ver §5.2) |
+
+**Body params:**
+
+| Param | Tipo | Obrigatório | Descrição |
+|---|---|---|---|
+| `content` | String | Sim (de fato) | Pedido em linguagem natural (tema, quantidade, idioma…). Vira a mensagem `user` enviada ao modelo |
+| `current` | Object | Não | Crossword atual do usuário. Se presente, é injetado como contexto (`system`) para o modelo **refinar/editar** em vez de criar do zero |
+
+**Comportamento real:**
+
+- O backend **não valida** `content`; se ausente, `content = null` e o modelo recebe uma mensagem `user` nula (comportamento indefinido do parse OpenAI).
+- O resultado **não é salvo**. O chamador é responsável por persistir.
+- `select` sofre dois níveis de tratamento: default local `5` em `AIRest` (se a IA omitir/enviar inválido) e clamp `[1,20]` (else `20`) em `Crossword.create`. Ver §5.1.
+- Logs vão para **stdout** (`System.out.println`), não para logger estruturado.
+
+**Exemplo de request:**
+
+```json
+POST /v3/ai/build/crossword
+Authorization: Bearer eyJhbGciOi...
+Content-Type: application/json
+
+{
+  "content": "Crie um crossword sobre frutas típicas do Brasil com 5 palavras"
+}
+```
+
+**Exemplo de response (200):**
+
+```json
+{
+  "_id": "665f0a91c8b0000000abcdef",
+  "title": "Desafio de Frutas Brasileiras",
+  "description": "Encontre as frutas típicas do Brasil.",
+  "words": [
+    { "number": 1, "direction": "vertical",   "row": 12, "column": 8,  "hint": "Fruta roxa amazônica usada em sucos", "word": "AÇAÍ" },
+    { "number": 2, "direction": "horizontal", "row": 13, "column": 6,  "hint": "Fruta pequena e roxa, nativa do Brasil", "word": "JABUTICABA" },
+    { "number": 3, "direction": "vertical",   "row": 10, "column": 11, "hint": "Fruta em forma de estrela quando cortada", "word": "CARAMBOLA" }
+  ]
+}
+```
+
+> O número, a posição e a quantidade de palavras variam a cada chamada — o exemplo é ilustrativo.
+
+---
+
+## 5. Regras de Negócio
+
+Regras presentes no **código** e ausentes de qualquer schema:
+
+### 5.1 `select` — dois níveis de tratamento
+
+- Em `AIRest.buildCrossword`: `int select = 5;` e só é sobrescrito se `parseInt(p.select)` tiver sucesso. Logo, **omissão da IA → `select = 5`**.
+- Em `Crossword.create`: `numTotalPalavras = (select < 1 || select > 20) ? 20 : select`. Ou seja, valores fora de `[1,20]` viram **20** (não 5). Exemplos: `0 → 20`, `30 → 20`, `7 → 7`.
+
+### 5.2 Saída não-determinística
+
+`escolherUmaPalavra` e `verifDisponibilidade` usam `java.util.Random` **sem seed**. A mesma entrada (mesmo `content` e até o mesmo conjunto de palavras) gera **tabuleiros diferentes** em chamadas distintas. Não há como reproduzir um layout.
+
+### 5.3 Pode posicionar **menos** palavras que `select`
+
+O laço para quando `faltam` esvazia, quando `adicionadas.size() == numPalavras` **ou** quando `tentativas >= faltam.size() * 2`. Palavras sem cruzamento válido vão para `puladas` e podem nunca entrar. Portanto `words.length ≤ select` — e frequentemente **menor**, sobretudo com poucas palavras no pool ou letras pouco compartilhadas.
+
+### 5.4 Primeira palavra é "principal" e sem restrição
+
+A palavra inicial é posicionada **vertical**, próxima ao centro, e marcada `isPrincipal = true`. É a única que entra sem precisar cruzar outra. Se ela for maior que 60 caracteres, **nada** é posicionado (a inicial é abortada e nenhuma outra tem âncora).
+
+### 5.5 Direção alternada
+
+`isVertical` é invertido a cada iteração do laço (`isVertical = !isVertical`), tendendo a alternar horizontal/vertical entre tentativas consecutivas.
+
+### 5.6 Cruzamento obrigatório e perpendicular
+
+`Checks.verifPalavra` só considera interseções com palavras de **direção oposta** (`palavraAdicionada.isVertical != isVertical`) que **compartilham uma letra**. `verifCasasNoTabuleiro` rejeita adjacências indevidas (palavras paralelas coladas) e exige letras coincidentes nos cruzamentos.
+
+### 5.7 Multi-tenant
+
+- Autenticação por `AuthBean` (Bearer). O crossword gerado **não é escopado** a nada (não persiste).
+- O prompt `intro_build_crossword` é inserido **uma vez** na coleção `AI_PROMPT` do tenant. É **global** — não há variação por usuário. Editá-lo no banco altera o comportamento de **todas** as gerações daquele tenant.
+
+### 5.8 Falhas de parse são silenciosas
+
+Cada extração de campo em `buildCrossword` é envolvida por `try/catch` que apenas faz `printStackTrace()`. Uma resposta malformada do modelo não retorna erro 4xx — degrada para valores default/`null`, podendo causar `NullPointerException` mais adiante (ver §9).
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+|---|---|---|---|
+| Inserção do prompt `intro_build_crossword` | Primeira chamada ao endpoint (quando `findPrompt` retorna `null`) | Cria o prompt introdutório hardcoded | **Sim** — coleção `AI_PROMPT` (global ao tenant) |
+| Geração de `_id` | `Crossword.builder()` em `create` | `ObjectId` hex de 24 chars | Não (só no objeto devolvido) |
+| Clamp de `select` | `Crossword.create` | Limita a `[1,20]`; fora disso → 20 | Não |
+| Recorte do tabuleiro | `ajustarTabuleiro()` | Remove bordas vazias, normaliza `row`/`column` à origem | Não |
+| Marcação `isPrincipal` | `posicionarPalavraInicial` | Primeira palavra marcada como principal (não exportado) | Não |
+| Logs em stdout | `Crossword.create` e `buildCrossword` | Imprime palavras, tabuleiro, modelo e uso de tokens no stdout | Não (apenas log de processo) |
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+
+- Geração de crossword por **tema em linguagem natural** (`content`).
+- **Refinamento** de um crossword existente (`current` injetado como contexto da IA).
+- Layout automático com cruzamentos perpendiculares e validação de adjacência.
+- Clamp de `select` para `[1,20]`.
+- Saída JSON pronta para o frontend: `_id`, `title`, `description`, `words[]` com `number`, `direction`, `row`, `column`, `hint`, `word`.
+
+### ❌ NÃO Suportado
+
+- **CRUD `/v3/crossword`** (GET / POST / PUT / DELETE) — **não existe**. Verificado por grep em `funifier-service`. O único endpoint é `POST /v3/ai/build/crossword`.
+- **Tela `/studio/crossword`** — não existe módulo Studio dedicado.
+- **Coleção MongoDB `crossword`** — o objeto **não é persistido**. Não há listagem, edição nem remoção pelo backend.
+- **Determinismo / reprodutibilidade** — saída varia entre chamadas (uso de `Random` sem seed).
+- **Garantia de posicionar todas as `select` palavras** — pode posicionar menos.
+- **`PUT`/atualização** de um crossword — inexistente (não há recurso para atualizar).
+- `gerarTabuleiro()` + `Utility.carregarPalavras` (carga de `src/com/diego/cruzadas/resources/palavras.txt`) — código **legado** que lê palavras de arquivo local; **não** é alcançado pelo fluxo de IA (que usa `gerarPalavrasAdicionadas`).
+- `posicionarPalavras___OLD()` — algoritmo antigo de posicionamento; **nunca chamado**.
+- Geração de DOCX (`Utility.gerarTabelaComum`, `salvarArquivoNormal`, `salvarArquivoRespondido`) — **comentada** no fonte.
+- `Cell.isInativa` — campo **declarado e lido** (`Checks.verifPalavra`) mas **nunca atribuído** → sempre `false` → o ramo que o consulta é morto.
+- Bloco inline comentado em `AIRest.java:1949-1991` — duplica `Crossword.create` com clamp antigo `> 10 ? 10` (limite depois elevado para 20 em `Crossword.create`).
+- `WordList`, `Utility.mostrarPalavras`, `Utility.separarPalavrasTamanho`, `Utility.setTableAlign` — auxiliares **somente** da geração DOCX legada.
+
+---
+
+## 8. Segurança e Permissões
+
+- **Autenticação:** Bearer token via `@BeanParam AuthBean`. Sem autorização granular específica para crossword.
+- **🔴 Token OpenAI hardcoded no fonte — `AIRest.java:79`:**
+  ```java
+  public static String CHATGPT_TOKEN = "Bearer sk-...<chave exposta>...";
+  ```
+  Segredo de API exposto em código versionado. Qualquer pessoa com acesso ao repositório pode consumir a chave (custo financeiro direto + risco de abuso). **Recomendação:** revogar a chave, movê-la para variável de ambiente / secret manager e remover do histórico do Git.
+- **Prompt injection:** `content` e `current` são repassados **diretamente** ao modelo como mensagens. Um usuário pode tentar manipular/escapar o prompt (jailbreak). O impacto é limitado — a saída é apenas um JSON de crossword montado por `Crossword.create` — mas conteúdo arbitrário pode aparecer em `title`/`description`/`hint`.
+- **Isolamento de tenant:** o prompt `intro_build_crossword` é **global** ao tenant (coleção `AI_PROMPT`). O crossword gerado não é escopado a nada por não ser persistido.
+- **Sem rate limiting** visível no método → cada chamada é uma requisição paga ao OpenAI; não há proteção contra abuso/loop de requisições.
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+**Diagnóstico:**
+
+- Não há logger estruturado. O método imprime no **stdout** do servidor:
+  - `ChatGPT Build : Crossword`, `ChatGPT Model : gpt-3.5-turbo-1106`, `ChatGPT Usage : {...}` (tokens), o JSON cru retornado, cada palavra adicionada e o tabuleiro ASCII (`imprimirTabuleiro`).
+- Para verificar se o módulo funciona: chamar o endpoint com um `content` simples e inspecionar a resposta (status 200 + `words[]` não vazio).
+
+**Erros comuns e causas:**
+
+| Sintoma | Causa provável |
+|---|---|
+| `500` / `NullPointerException` | `words` não parseado (`map == null`) → `Crossword.create` faz `wordsRepository.keySet()` sobre `null`. Ocorre quando a IA não retorna o campo `words` ou retorna formato inesperado |
+| `500` no parse do retorno | OpenAI não retornou `function_call` (ex.: token inválido/expirado, indisponibilidade) → `message.getFunctionCall()` é `null` |
+| `title`/`description` valendo a string `"null"` | A IA omitiu o campo; `String.valueOf(p.get("title"))` produz `"null"` literal |
+| `words` com menos itens que o pedido | Normal — palavras sem cruzamento válido foram puladas, ou `tentativas >= faltam.size()*2` (ver §5.3) |
+| Resposta sem nenhuma palavra | Pool com 1 palavra e ela maior que 60 chars, ou nenhuma interseção encontrada após a inicial |
+
+**Comandos úteis:**
+
+```
+POST /v3/ai/build/crossword          { "content": "crossword sobre capitais do Brasil, 8 palavras" }
+POST /v3/ai/build/crossword          { "content": "...", "current": { ...crossword existente... } }
+```
+
+Inspeção do prompt global (via API de IA/prompts do tenant), caso o comportamento da geração precise ser ajustado: procurar o documento `_id = "intro_build_crossword"` na coleção `AI_PROMPT`.
+
+---
+
+## 10. Exemplos Práticos
+
+### Exemplo mínimo
+
+```json
+POST /v3/ai/build/crossword
+{ "content": "Crie um crossword sobre animais da savana com 5 palavras" }
+```
+
+Devolve um `Crossword` com `_id`, `title`, `description` e até 5 palavras posicionadas.
+
+### Exemplo avançado — refinar um crossword existente
+
+```json
+POST /v3/ai/build/crossword
+{
+  "content": "Troque as palavras muito difíceis por outras mais fáceis e mantenha o tema",
+  "current": {
+    "title": "Desafio de Frutas Brasileiras",
+    "description": "Encontre as frutas típicas do Brasil.",
+    "words": [
+      { "number": 1, "direction": "vertical", "row": 12, "column": 8, "hint": "Fruta roxa amazônica", "word": "AÇAÍ" }
+    ]
+  }
+}
+```
+
+O `current` é injetado como contexto `system`; o modelo gera um novo conjunto de palavras/dicas e o motor remonta o tabuleiro.
+
+### Anti-pattern (o que NÃO fazer)
+
+- ❌ Chamar `GET /v3/crossword` ou `DELETE /v3/crossword/:id` — **não existem**. Não há CRUD.
+- ❌ Esperar que o backend **salve** o crossword. Ele apenas devolve; persistência é responsabilidade do chamador.
+- ❌ Depender da **mesma saída** para a mesma entrada — o layout é aleatório.
+- ❌ Pedir `select` muito alto achando que vem mais palavras — acima de 20 vira 20, e o tabuleiro ainda pode posicionar menos.
+- ❌ Confiar no token OpenAI hardcoded em produção — deve ser externalizado (ver §8).
+
+---
+
+## Checklist de Configuração
+
+- [ ] Token OpenAI **válido** disponível (hoje hardcoded em `AIRest.java:79` — externalizar e revogar a chave exposta).
+- [ ] `content` descreve **tema + quantidade** (e idioma/formato, se necessário) de forma clara.
+- [ ] O chamador **persiste** o crossword retornado (o backend não persiste).
+- [ ] Não depender de **determinismo** — tratar cada resposta como nova.
+- [ ] `select` entre **1 e 20** (fora disso o backend força 20).
+- [ ] Tratar o caso de **`words` vir vazio ou menor** que o solicitado.
+- [ ] Armadilha silenciosa: se a IA **omitir `words`**, a geração pode lançar `NullPointerException` (500) — validar o retorno.
+
+## Steps
+
+### Sobre Crosswords
+
+Palavras cruzadas têm: **título** → **palavras** (com dicas e posições na grade) → **tema visual**.
+O Studio (`/studio/crossword`) fornece editor visual para posicionar as palavras na grade.
+
+---
+
+## Steps
+
+### 1. Verificar se já existe
+
+```
+funifier_list type=crossword search=<titulo>
+```
+
+### 2. Ler a documentação do módulo
+
+```
+datasource-funifier-docs/knowledge/modules/crossword.md
+```
+
+### 3. Criar o crossword
+
+```json
+{
+  "title": "Tech Vocabulary",
+  "description": "Test your technical vocabulary.",
+  "active": true
+}
+```
+
+```
+funifier_save type=crossword payload=<json>
+```
+
+### 4. Adicionar palavras e posições
+
+Use o editor visual do Studio (`/studio/crossword`) para posicionar palavras na grade e definir dicas.
+
+Para criação via API, consulte `GET /v3/crossword/:id` em um crossword existente para entender a estrutura de campos das palavras (`words`, `position`, `clue`, `direction`).
+
+### 5. Validar
+
+```
+funifier_list type=crossword search=<titulo>
+```
+
+Teste o jogo no Studio e verifique que as dicas e palavras estão corretas.