docs: document the IA module

README: add ia to the modules table, the four ia permissions, and a full
IA section covering commands, profile switching, operator corrections,
memory/context, and the key + rate-limit model. Notes the safety boundary
(no tools, reply never executed, leading slashes stripped) and which config
values are baked vs live.

Co-Authored-By: Claude <noreply@anthropic.com>

README.md

@@ -20,6 +20,7 @@ All player-facing text is Portuguese (pt-BR).
 | `enquete` | `/enquete Pergunta \| A \| B` — clickable voting with a live tally on the boss bar. |
 | `ranking` | `/ranking mineracao` and friends. Covers **offline players too**. |
 | `marcos` | Announces round milestones — 100 km walked, 24 hours played — the first time someone crosses one. |
+| `ia` | `/ia <pergunta>` asks an OpenAI-compatible model in chat. Optional wiki grounding, per-player memory, operator corrections. |
 
 Toggle any of them: `/canalhandia modulo <nome> <on|off>`
 
@@ -184,6 +185,10 @@ survive a restart.
 | `canalhandia.forcar` | op | trigger curiosities and guess rounds |
 | `canalhandia.admin` | op | change modules and all settings |
 | `canalhandia.isento` | nobody | never be the subject |
+| `canalhandia.ia` | op | `/ia` (public question, broadcast to chat) |
+| `canalhandia.ia.privado` | op | `/iap` (private question, answer only to the asker) |
+| `canalhandia.ia.corrigir` | op | `/ia corrigir <resposta>` — register a correction for the last answer |
+| `canalhandia.ia.perfil` | op | `/ia perfil <economico\|preciso>` — switch profile live |
 
 Permissions are **declared explicitly** in `plugin.yml`. An undeclared Bukkit
 permission falls back to op-only, which would silently stop normal players from
@@ -191,6 +196,79 @@ reacting.
 
 ---
 
+## IA (`/ia`)
+
+Chat Q&A backed by an OpenAI-compatible endpoint (default MiniMax). Gated to
+operator + LuckPerms-permitted players; both `/ia` and `/iap` default to op and
+are granted independently, so an operator can let someone ask privately without
+letting them broadcast.
+
+**The model can only ever produce chat text.** No tool/function definitions are
+sent in the request, the reply is passed to `sendMessage` and nowhere else, and
+`AiText.sanitise` strips leading slashes so a reply cannot be mistaken for a
+command. A player asking it to "run `/op me`" gets a string back, not an
+executed command.
+
+### Commands
+
+| Command | What it does |
+|---|---|
+| `/ia <pergunta>` | Asks the model. Public by default — the question and answer broadcast. Needs `canalhandia.ia`. |
+| `/iap <pergunta>` | Asks privately — the answer goes only to the asker. Needs `canalhandia.ia.privado`. |
+| `/ia perfil <economico\|preciso>` | Switches profile live. `ECONOMICO` skips the wiki (fast); `PRECISO` consults the Minecraft Wiki (slower, grounded). Needs `canalhandia.ia.perfil`. |
+| `/ia corrigir <resposta correta>` | Records a correction for the last answered question. Future similar questions get it as context — the cheap alternative to fine-tuning. Needs `canalhandia.ia.corrigir`. |
+| `/ia feedback ruim` | Flags the last answer wrong (in-memory counter shown in `/canalhandia status`). |
+| `/errado` | The `[ERRADO]` reaction to the last message — the typed-twin of the reaction button, for Bedrock players. |
+
+Subcommands only hijack when their second token is one they act on (a known
+profile key, or `ruim`), so `/ia perfil do servidor` falls through and is asked.
+`corrigir` stays greedy — a correction always reads the rest of the line.
+
+### Profile
+
+`ECONOMICO` skips the wiki round trip — fast, ungrounded. `PRECISO` runs a
+forced tool call to pick a wiki term, looks it up on pt.minecraft.wiki, and
+injects the article as context. Switch live with `/ia perfil`; the choice is
+read per-question, so it takes effect immediately.
+
+### Operator corrections
+
+`/ia corrigir <resposta>` appends to `plugins/Canalhandia/correcoes.yml`. When a
+new question shares at least one significant word (length > 4) with a recorded
+correction, the correction is injected as system context. Pure string matching,
+no model round trip.
+
+### Memory and context
+
+- **Per-player memory**: the last `memoria-perguntas` exchanges within
+  `memoria-minutos` are replayed, for follow-ups like "e no nether?". Forgotten
+  on quit. Baked at construction; not hot-swappable.
+- **Server context**: the `contexto:` list in `config.yml` is facts the model
+  would never know (server name, Bedrock prefix, installed mods). Sent on every
+  question.
+- **Recipes**: `RecipeBook` snapshots `Bukkit.recipeIterator()` at enable (main
+  thread) and answers recipe questions from that snapshot — `explaintext` drops
+  tables, so the wiki cannot supply them.
+
+### Keys and limits
+
+The API key never lives in `config.yml` (committed to git). Read from the
+`MINIMAX_API_KEY` env var, or `plugins/Canalhandia/minimax.key` (one line,
+printable ASCII only — control chars are stripped so a stray newline can't
+land the key in a server-log header exception).
+
+Per-player cooldown (`cooldown-segundos`), a server-wide daily cap
+(`limite-diario`), and a one-question-at-a-time guard per player keep the
+token spend bounded. `canalhandia.admin` skips the cooldown.
+
+The four values `url`, `wiki-caracteres`, `memoria-perguntas` and
+`memoria-minutos` are baked at construction. Everything else — `modelo`,
+`max-tokens`, `temperatura`, `instrucoes`, `perfil`, `contexto`, the limits —
+is read live, so operators can hot-swap them with `/canalhandia reload` or the
+`/ia perfil` command without a restart.
+
+---
+
 ## Building
 
 Requires **JDK 25**. Paper 26.2's API ships Java 25 class files, and JDK 21 fails