From d7a7d6350d93c2ee67a9fc5e7b802e16bf0702f4 Mon Sep 17 00:00:00 2001
From: Henri Bourcereau <henri.bourcereau@gmail.com>
Date: Thu, 15 Jan 2026 17:03:16 +0100
Subject: [PATCH] refact: docs

---
 README.md                                     | 34 +++++++++++++++++--
 doc/{refs => ai}/claudeAIquestion.md          |  0
 doc/{refs => ai}/claudeAIquestionOnlyRust.md  |  0
 doc/{refs => ai}/geminiQuestions.md           |  0
 doc/{ => book}/traité.md                      |  0
 doc/{ => specs}/diagrammes.md                 |  0
 .../stateEncoding.md}                         |  0
 doc/{ => specs}/store.puml                    |  0
 doc/{ => specs}/vocabulary.md                 |  0
 doc/{ => specs}/workflow.md                   |  0
 10 files changed, 32 insertions(+), 2 deletions(-)
 rename doc/{refs => ai}/claudeAIquestion.md (100%)
 rename doc/{refs => ai}/claudeAIquestionOnlyRust.md (100%)
 rename doc/{refs => ai}/geminiQuestions.md (100%)
 rename doc/{ => book}/traité.md (100%)
 rename doc/{ => specs}/diagrammes.md (100%)
 rename doc/{refs/specifications.md => specs/stateEncoding.md} (100%)
 rename doc/{ => specs}/store.puml (100%)
 rename doc/{ => specs}/vocabulary.md (100%)
 rename doc/{ => specs}/workflow.md (100%)

diff --git a/README.md b/README.md
index d2808fa..c7f4e75 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,37 @@
 # Trictrac
 
-Game of [Trictrac](https://en.wikipedia.org/wiki/Trictrac) in rust.
+This is a game of [Trictrac](https://en.wikipedia.org/wiki/Trictrac) rust implementation.
 
-wip
+The project is on its early stages.
+Rules (without "schools") are implemented, you can play in a terminal against a bot which plays randomly.
 
+Training of AI bots is the work in progress.
 
+## Roadmap
+
+[x] rules
+[x] command line interface
+[x] basic bot (random play)
+[.] AI bot
+[] network game
+[] web client
+
+## Code structure
+
+- game rules and game state are implemented in the _store/_ folder.
+- the command-line application is implemented in _client_cli/_; it allows you to play against a bot, or to have two bots play against each other
+- the bots algorithms and the training of their models are implemented in the _bot/_ folder
+
+### _store_ package
+
+The game state is defined by the `GameState` struct in _store/src/game.rs_. The `to_string_id()` method allows this state to be encoded compactly in a string (without the played moves history). For a more readable textual representation, the `fmt::Display` trait is implemented.
+
+### _client_cli_ package
+
+`client_cli/src/game_runner.rs` contains the logic to make two bots play against each other.
+
+### _bot_ package
+
+- `bot/src/strategy/default.rs` contains the code for a basic bot strategy: it determines the list of valid moves (using the `get_possible_moves_sequences` method of `store::MoveRules`) and simply executes the first move in the list.
+- `bot/src/strategy/dqnburn.rs` is another bot strategy that uses a reinforcement learning trained model with the DQN algorithm via the burn library (<https://burn.dev/>).
+- `bot/scripts/trains.sh` allows you to train agents using different algorithms (DQN, PPO, SAC).
diff --git a/doc/refs/claudeAIquestion.md b/doc/ai/claudeAIquestion.md
similarity index 100%
rename from doc/refs/claudeAIquestion.md
rename to doc/ai/claudeAIquestion.md
diff --git a/doc/refs/claudeAIquestionOnlyRust.md b/doc/ai/claudeAIquestionOnlyRust.md
similarity index 100%
rename from doc/refs/claudeAIquestionOnlyRust.md
rename to doc/ai/claudeAIquestionOnlyRust.md
diff --git a/doc/refs/geminiQuestions.md b/doc/ai/geminiQuestions.md
similarity index 100%
rename from doc/refs/geminiQuestions.md
rename to doc/ai/geminiQuestions.md
diff --git a/doc/traité.md b/doc/book/traité.md
similarity index 100%
rename from doc/traité.md
rename to doc/book/traité.md
diff --git a/doc/diagrammes.md b/doc/specs/diagrammes.md
similarity index 100%
rename from doc/diagrammes.md
rename to doc/specs/diagrammes.md
diff --git a/doc/refs/specifications.md b/doc/specs/stateEncoding.md
similarity index 100%
rename from doc/refs/specifications.md
rename to doc/specs/stateEncoding.md
diff --git a/doc/store.puml b/doc/specs/store.puml
similarity index 100%
rename from doc/store.puml
rename to doc/specs/store.puml
diff --git a/doc/vocabulary.md b/doc/specs/vocabulary.md
similarity index 100%
rename from doc/vocabulary.md
rename to doc/specs/vocabulary.md
diff --git a/doc/workflow.md b/doc/specs/workflow.md
similarity index 100%
rename from doc/workflow.md
rename to doc/specs/workflow.md