prashantchahar · Copilot · Apr 20, 2026 · Apr 20, 2026
diff --git a/README.es.md b/README.es.md
@@ -1,11 +1,84 @@
 <!-- l10n-sync: source-file="README.md" -->
 🌐 [Português (BR)](README.pt_BR.md) | [Español](README.es.md)
 
-# Soc Ops
+# 🎯 Soc Ops — Bingo Social
 
-Juego de Bingo Social para encuentros presenciales. ¡Encuentra personas que coincidan con las preguntas y consigue 5 en fila!
+> **¡Rompe el hielo, haz conexiones, gana en el networking!**
 
----
+Soc Ops es un juego de bingo social interactivo diseñado para encuentros presenciales, eventos de equipo y conferencias. ¡Encuentra personas que coincidan con las preguntas, marca tu cartón y corre a conseguir 5 en fila!
+
+## ✨ Características
+
+- 🎲 **Tableros aleatorios** — Cada jugador obtiene una disposición única
+- 💾 **Guardado automático** — Retoma donde lo dejaste
+- 🏆 **Detección de bingo** — Detección automática de filas, columnas y diagonales
+- 🎉 **Modal de celebración** — Pantalla de victoria digna de confeti
+- 📱 **Mobile-first** — Funciona genial en teléfonos durante eventos
+
+## 🚀 Inicio Rápido
+
+### Requisitos Previos
+- [Python 3.13+](https://www.python.org/downloads/)
+- [uv](https://docs.astral.sh/uv/) (gestor de paquetes Python)
+
+### Ejecutar Localmente
+```bash
+uv sync
+uv run uvicorn app.main:app --reload --port 8000
+# Abre http://localhost:8000
+```
+
+### Pruebas
+```bash
+uv run pytest
+```
+
+### Linting
+```bash
+uv run ruff check .
+```
+
+## 🎨 Personaliza Tu Juego
+
+### Cambiar Preguntas
+Edita `app/data.py` para agregar tus propias preguntas rompe-hielo:
+```python
+questions_list: list[str] = [
+    "tiene una mascota",
+    "habla más de 2 idiomas",
+    "tu pregunta personalizada aquí",
+    # ... 24+ preguntas para un tablero completo
+]
+```
+
+### Guía del Taller
+👉 Sigue la [Guía del Lab](workshop/GUIDE.md) para una experiencia práctica con los agentes de GitHub Copilot.
+
+## 🛠️ Stack Tecnológico
+
+- **Framework**: FastAPI + Jinja2 + HTMX
+- **Estilos**: Utilidades CSS personalizadas (inspiradas en Tailwind)
+- **Estado**: Sesiones del lado del servidor con persistencia de cookies
+- **Despliegue**: GitHub Pages mediante Actions
+
+## 📁 Estructura del Proyecto
+
+```
+app/
+├── templates/       # Plantillas Jinja2
+│   ├── base.html
+│   ├── home.html
+│   └── components/  # bingo_board, bingo_modal, game_screen, start_screen
+├── static/          # Recursos CSS y JS
+├── models.py        # Estado del juego y modelos de datos
+├── game_logic.py    # Detección de bingo y generación de tablero
+├── game_service.py  # Gestión de sesiones
+├── data.py          # Banco de preguntas
+└── main.py          # Rutas FastAPI
+tests/
+├── test_api.py      # Pruebas de endpoints de la API
+└── test_game_logic.py  # Pruebas unitarias de lógica del juego
+```
 
 ## 📚 Guía del Laboratorio
 
@@ -19,8 +92,11 @@ Juego de Bingo Social para encuentros presenciales. ¡Encuentra personas que coi
 
 > 📝 Las guías del laboratorio también están disponibles en la carpeta [`workshop/`](workshop/) para lectura sin conexión.
 
----
+## 🚢 Despliegue
+
+Se despliega automáticamente en GitHub Pages al hacer push a `main`:
+- Tu juego: `https://{usuario}.github.io/{nombre-repo}`
 
-## 🚀 Primeros Pasos
+## 📝 Licencia
 
-Dirígete a **[Parte 00: Visión General](https://copilot-dev-days.github.io/agent-lab-python/step.html?step=00-overview)** para los requisitos previos e instrucciones de configuración.
+MIT — ¡úsalo en tu próximo evento!
diff --git a/README.md b/README.md
@@ -1,10 +1,83 @@
 🌐 [Português (BR)](README.pt_BR.md) | [Español](README.es.md)
 
-# Soc Ops
+# 🎯 Soc Ops — Social Bingo
 
-Social Bingo game for in-person mixers. Find people who match the questions and get 5 in a row!
+> **Break the ice, make connections, win at networking!**
 
----
+Soc Ops is an interactive social bingo game designed for in-person mixers, team events, and conferences. Find people who match the prompts, mark your card, and race to get 5 in a row!
+
+## ✨ Features
+
+- 🎲 **Randomized boards** — Every player gets a unique arrangement
+- 💾 **Auto-save progress** — Pick up where you left off
+- 🏆 **Bingo detection** — Automatic win detection for rows, columns, and diagonals
+- 🎉 **Celebration modal** — Confetti-worthy victory screen
+- 📱 **Mobile-first** — Works great on phones at events
+
+## 🚀 Quick Start
+
+### Prerequisites
+- [Python 3.13+](https://www.python.org/downloads/)
+- [uv](https://docs.astral.sh/uv/) (Python package manager)
+
+### Run Locally
+```bash
+uv sync
+uv run uvicorn app.main:app --reload --port 8000
+# Open http://localhost:8000
+```
+
+### Test
+```bash
+uv run pytest
+```
+
+### Lint
+```bash
+uv run ruff check .
+```
+
+## 🎨 Customize Your Game
+
+### Change Questions
+Edit `app/data.py` to add your own icebreaker prompts:
+```python
+questions_list: list[str] = [
+    "has a pet",
+    "speaks more than 2 languages",
+    "your custom question here",
+    # ... 24+ questions for a full board
+]
+```
+
+### Workshop Guide
+👉 Follow the [Lab Guide](workshop/GUIDE.md) for a hands-on workshop experience with GitHub Copilot agents.
+
+## 🛠️ Tech Stack
+
+- **Framework**: FastAPI + Jinja2 + HTMX
+- **Styling**: Custom CSS utilities (Tailwind-inspired)
+- **State**: Server-side sessions with cookie persistence
+- **Deployment**: GitHub Pages via Actions
+
+## 📁 Project Structure
+
+```
+app/
+├── templates/       # Jinja2 templates
+│   ├── base.html
+│   ├── home.html
+│   └── components/  # bingo_board, bingo_modal, game_screen, start_screen
+├── static/          # CSS & JS assets
+├── models.py        # Game state & data models
+├── game_logic.py    # Bingo detection & board generation
+├── game_service.py  # Session management
+├── data.py          # Question bank
+└── main.py          # FastAPI routes
+tests/
+├── test_api.py      # API endpoint tests
+└── test_game_logic.py  # Game logic unit tests
+```
 
 ## 📚 Lab Guide
 
@@ -18,8 +91,11 @@ Social Bingo game for in-person mixers. Find people who match the questions and
 
 > 📝 Lab guides are also available in the [`workshop/`](workshop/) folder for offline reading.
 
----
+## 🚢 Deployment
+
+Automatically deploys to GitHub Pages on push to `main`:
+- Your game: `https://{username}.github.io/{repo-name}`
 
-## 🚀 Getting Started
+## 📝 License
 
-Head to **[Part 00: Overview](https://copilot-dev-days.github.io/agent-lab-python/step.html?step=00-overview)** for prerequisites and setup instructions.
+MIT — use it for your next event!
diff --git a/README.pt_BR.md b/README.pt_BR.md
@@ -1,11 +1,84 @@
 <!-- l10n-sync: source-file="README.md" -->
 🌐 [Português (BR)](README.pt_BR.md) | [Español](README.es.md)
 
-# Soc Ops
+# 🎯 Soc Ops — Bingo Social
 
-Jogo de Bingo Social para encontros presenciais. Encontre pessoas que correspondam às perguntas e consiga 5 em linha!
+> **Quebre o gelo, faça conexões, ganhe no networking!**
 
----
+Soc Ops é um jogo de bingo social interativo projetado para encontros presenciais, eventos de equipe e conferências. Encontre pessoas que correspondam às perguntas, marque seu cartão e corra para conseguir 5 em linha!
+
+## ✨ Funcionalidades
+
+- 🎲 **Cartelas aleatórias** — Cada jogador recebe uma disposição única
+- 💾 **Progresso salvo automaticamente** — Continue de onde parou
+- 🏆 **Detecção de bingo** — Detecção automática em linhas, colunas e diagonais
+- 🎉 **Modal de celebração** — Tela de vitória digna de confete
+- 📱 **Mobile-first** — Funciona muito bem em celulares durante eventos
+
+## 🚀 Início Rápido
+
+### Pré-requisitos
+- [Python 3.13+](https://www.python.org/downloads/)
+- [uv](https://docs.astral.sh/uv/) (gerenciador de pacotes Python)
+
+### Executar Localmente
+```bash
+uv sync
+uv run uvicorn app.main:app --reload --port 8000
+# Abra http://localhost:8000
+```
+
+### Testes
+```bash
+uv run pytest
+```
+
+### Lint
+```bash
+uv run ruff check .
+```
+
+## 🎨 Personalize Seu Jogo
+
+### Alterar Perguntas
+Edite `app/data.py` para adicionar seus próprios prompts de quebra-gelo:
+```python
+questions_list: list[str] = [
+    "tem um animal de estimação",
+    "fala mais de 2 idiomas",
+    "sua pergunta personalizada aqui",
+    # ... 24+ perguntas para uma cartela completa
+]
+```
+
+### Guia do Workshop
+👉 Siga o [Guia do Lab](workshop/GUIDE.md) para uma experiência prática com os agentes do GitHub Copilot.
+
+## 🛠️ Stack Tecnológica
+
+- **Framework**: FastAPI + Jinja2 + HTMX
+- **Estilos**: Utilitários CSS personalizados (inspirados no Tailwind)
+- **Estado**: Sessões no lado do servidor com persistência em cookies
+- **Implantação**: GitHub Pages via Actions
+
+## 📁 Estrutura do Projeto
+
+```
+app/
+├── templates/       # Templates Jinja2
+│   ├── base.html
+│   ├── home.html
+│   └── components/  # bingo_board, bingo_modal, game_screen, start_screen
+├── static/          # Recursos CSS e JS
+├── models.py        # Estado do jogo e modelos de dados
+├── game_logic.py    # Detecção de bingo e geração de cartela
+├── game_service.py  # Gerenciamento de sessões
+├── data.py          # Banco de perguntas
+└── main.py          # Rotas FastAPI
+tests/
+├── test_api.py      # Testes de endpoints da API
+└── test_game_logic.py  # Testes unitários de lógica do jogo
+```
 
 ## 📚 Guia do Lab
 
@@ -19,8 +92,11 @@ Jogo de Bingo Social para encontros presenciais. Encontre pessoas que correspond
 
 > 📝 Os guias do lab também estão disponíveis na pasta [`workshop/`](workshop/) para leitura offline.
 
----
+## 🚢 Implantação
+
+Implanta automaticamente no GitHub Pages ao fazer push para `main`:
+- Seu jogo: `https://{usuario}.github.io/{nome-repo}`
 
-## 🚀 Primeiros Passos
+## 📝 Licença
 
-Acesse **[Parte 00: Visão Geral](https://copilot-dev-days.github.io/agent-lab-python/step.html?step=00-overview)** para pré-requisitos e instruções de configuração.
+MIT — use para o seu próximo evento!