improved readme with "how to play" section

README.md

@@ -24,7 +24,7 @@ tags:
 
 [My post on LinkedIn](https://www.linkedin.com/posts/luca-di-palma-99024a1b7_most-of-us-use-llms-to-create-reports-write-activity-7400225424770932736-OTPU?utm_source=share&utm_medium=member_desktop&rcm=ACoAADJnVPwBh-8LoV25AQVeclIBTKNuOP6rr08)
 
-**New to Codenames? No problem. Check out the example in the 'How to Play' tab to get started!**
+**New to Codenames? No problem.** Go to the [How to Play section](#-how-to-play) below or check out the example in the _How to Play_ tab in the app to get started.
 
 ---
 
@@ -95,7 +95,7 @@ Your AI teammates will interpret your hint and take their guesses.
 
 ## 🕹️ Main Features
 
-* **Create & customize teams** using any mix of LLMs
+* **Build teams by selecting providers** or choose `random` to generate a mixed-model team.
 * **Switch between AI vs AI** and **Human vs AI** modes
 * **Detailed per-turn logs** for all model decisions
 * **Transparent reasoning chains**
@@ -116,4 +116,101 @@ The Stats section of the app includes:
 
 This turns the Arena into a dynamic benchmarking tool for evaluating LLM semantic reasoning, coordination abilities, and reliability under pressure.
 
+---
+
+## ❓ How to Play
+
+
+### 📝 Summary
+
+Codenames is a word-association game where two teams compete to guess all their secret words before the opponents do. Each team has a Boss who **can see** a hidden color-coded board showing which words belong to their team, which belong to the other team, which are neutral, and which single word is the deadly assassin. The Boss gives one-word clues paired with a number, hinting at how many words on the board relate to that clue. Their teammates, **who cannot see any colors**, must discuss, interpret the clue, and decide which words the Boss is pointing toward. Choosing their own words brings them closer to victory, while accidentally selecting an opponent’s word, a neutral word, or the assassin can derail their progress or end the game instantly. The goal is simple: interpret clues wisely, avoid dangerous words, and be the first team to uncover all your hidden words.
+
+### 💡 Let's see an example
+
+What Bosses see (left) VS what other players see (right)
+
+<img src="assets/example.png" alt="Example board" width="400">
+<img src="assets/no-color-board.png" alt="Example board" width="400">
+
+### 👥 Team Roles
+
+Each team has four members with distinct responsibilities:
+
+* **1 Boss** 🎯: The only player who can see the color-coded board. Provides clues to guide the team.
+* **1 Captain** 🧭: Coordinates team reasoning, synthesizes suggestions, and makes final word selections.
+* **2 Players** 💭: Collaborate with the Captain, propose interpretations and associations.
+
+---
+
+### 🎮 How a Turn Works
+
+#### 1️⃣ Boss Gives a Clue
+
+The Red Boss (seeing the board) might say:
+
+> **"Atmosphere: 2"**
+
+This clue suggests 2 red words are related to *atmosphere*. Looking at the board, the Boss is thinking of:
+
+* **AIR** (part of the atmosphere)
+* **SPACE** (beyond the atmosphere)
+
+*⚠️ Important: The clue must be ONE word and ONE number. The number indicates how many words relate to that clue.*
+
+---
+
+#### 2️⃣ Team Discussion
+
+The Captain and Players discuss without seeing the colors:
+
+* **Player 1:** “AIR feels like the safest bet — it's literally the atmosphere.”
+* **Player 2:** “SPACE could connect because it's outside the atmosphere.”
+
+---
+
+#### 3️⃣ Captain Makes Final Selection
+
+The Captain decides which words to touch, in order:
+
+1. AIR ✅ (Red — Correct!)
+2. SPACE ✅ (Red — Correct!)
+
+The team can stop after any correct guess or continue up to the number given (+1 bonus from previous turns if applicable).
+
+---
+
+### ⚠️ Mistakes to Avoid
+
+* Guessing **STAFF** (black — killer word) ends the game **immediately**. They **lose**!
+* Guessing **WALL** (blue — opponent’s word) ends the turn and gives that word to the Blue team.
+* Guessing **SATURN** (beige — neutral) simply ends the turn.
+
+---
+
+### 🏆 Winning the Game
+
+The game ends when:
+
+* ✅ **A team finds all their colored words** → That team wins!
+* ❌ **A team touches the killer word (STAFF)** → That team loses immediately!
+
+---
+
+### 💡 Strategy Tips
+
+#### For the Boss:
+
+* Try to link multiple words with creative clues
+* Avoid clues that may lead to the killer or opponent’s words
+* Consider associations your team might make
+
+#### For Captain & Players:
+
+* Discuss all possible interpretations
+* Consider risky words
+* Don’t be afraid to stop early to avoid the killer word
+* The Captain has final say but should consider all suggestions
+
+
+
 

pages/how_to_play.py

@@ -14,9 +14,16 @@ with gr.Blocks(fill_width=True) as demo:
                 show_label=True,
                 height=450,
                 elem_id="example_game_board_img",
+            ),
+            gr.Image(
+                "assets/no-color-board.png",
+                label="“Captains' and Players' View",
+                show_label=True,
+                height=450,
+                elem_id="example_game_board_img",
             )
         with gr.Column():
             gr.HTML(EXAMPLE_GAME_RULES_HTML, elem_id="rules_content")
 
 if __name__ == "__main__":
-    demo.launch()
+    demo.launch()

support/game_settings.py

@@ -132,7 +132,7 @@ EXAMPLE_GAME_BOARD_HTML = """
             <li><strong style="color: #6c757d;">Beige squares</strong> = Neutral words (innocent bystanders)</li>
             <li><strong style="color: #212529;">Black square</strong> = Killer word (instant loss if touched!)</li>
         </ul>
-        <p><strong>Remember:</strong> Only the <strong>Boss</strong> sees these colors. The <strong>Captain</strong> and <strong>Players</strong> only see the words!</p>
+        <p><strong>Remember:</strong> Only the <strong>Boss</strong> sees these colors (image above). The <strong>Captain</strong> and <strong>Players</strong> only see the words (image below)!</p>
     </div>
 </div>
 """