From d8635e59cbcdab3713c52a5db6b466545c17274c Mon Sep 17 00:00:00 2001
From: Guillaume ARM <trapcodien@gmail.com>
Date: Tue, 9 Jun 2026 20:34:30 +0200
Subject: [PATCH] docs: added trapgpt_guide.md

---
 docs/trapgpt_guide.md | 105 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 105 insertions(+)
 create mode 100644 docs/trapgpt_guide.md

diff --git a/docs/trapgpt_guide.md b/docs/trapgpt_guide.md
new file mode 100644
index 0000000..0d4337f
--- /dev/null
+++ b/docs/trapgpt_guide.md
@@ -0,0 +1,105 @@
+# TrapGPT Guide
+
+TrapGPT est un serveur TrapOS qui ecoute le chat Minecraft avec une Chat Box Advanced Peripherals, envoie les nouveaux messages a `opencode serve`, puis repond tres brievement dans le chat.
+
+## Prerequis
+
+- Une Chat Box Advanced Peripherals connectee au computer.
+- TrapOS installe avec le package `trapos-ai`.
+- Un serveur `opencode serve` accessible depuis ComputerCraft HTTP.
+- HTTP active cote serveur Minecraft/ComputerCraft.
+
+Voir aussi [`docs/opencode_server_guide.md`](opencode_server_guide.md) pour lancer `opencode serve`.
+
+## Configuration In-Game
+
+Dans le computer qui porte la chatbox, configure l'URL du serveur opencode:
+
+```lua
+set opencc.server_url http://host:port
+set opencc.username opencode
+```
+
+Si ton serveur opencode demande un mot de passe Basic Auth:
+
+```lua
+set opencc.password ton_mot_de_passe
+```
+
+Settings optionnels pour TrapGPT:
+
+```lua
+set trapgpt.throttle_seconds 5
+set trapgpt.max_reply_chars 160
+set trapgpt.prefix TrapGPT
+```
+
+Sauvegarde les settings:
+
+```lua
+settings save
+```
+
+## Lancement
+
+Depuis le shell CraftOS:
+
+```lua
+trapgpt
+```
+
+Le programme affiche:
+
+```text
+trapgpt listening
+```
+
+Ensuite, parle normalement dans le chat Minecraft. TrapGPT collecte les messages, attend le throttle, envoie les nouveaux messages au LLM, puis poste une reponse courte dans le chat.
+
+## Comportement
+
+- TrapGPT ecoute pour l'instant seulement les messages joueur `chat`.
+- Les morts et connexions seront ajoutes plus tard.
+- Il ne lance jamais deux appels LLM en meme temps.
+- Les messages recus pendant un appel opencode sont gardes en queue.
+- Si plusieurs messages sont en queue, ils sont envoyes ensemble au batch suivant.
+- La session opencode est separee du programme `ai`: elle utilise `trapgpt.opencc.session_id`.
+- Si le LLM repond exactement `SILENCE`, rien n'est envoye dans le chat.
+
+## Redemarrer Une Session TrapGPT
+
+Si tu veux repartir avec une nouvelle conversation opencode pour TrapGPT:
+
+```lua
+lua
+require('/apis/libai')().clearSession({ sessionSettingKey = 'trapgpt.opencc.session_id' })
+exit()
+```
+
+Puis relance:
+
+```lua
+trapgpt
+```
+
+## Depannage
+
+Si `chat_box peripheral not found` apparait:
+
+- Verifie que la Chat Box est bien collee/connectee au computer.
+- En 1.21.1+, le nom de peripheral attendu est souvent `chat_box`.
+- Sur anciennes versions, TrapGPT tente aussi `chatBox`.
+
+Si TrapGPT ne repond pas:
+
+- Verifie `opencc.server_url`.
+- Verifie que `opencode serve` tourne.
+- Verifie que HTTP est autorise dans la config ComputerCraft.
+- Attends au moins `trapgpt.throttle_seconds` secondes.
+- Le LLM peut aussi avoir repondu `SILENCE`, donc rien n'est poste.
+
+Pour voir la version installee:
+
+```lua
+trapgpt --version
+```