Create README.md

README.md

@@ -1,14 +1,93 @@
----
-title: Science Talk Adventure
-emoji: 🚀
-colorFrom: pink
-colorTo: pink
-sdk: gradio
-sdk_version: 5.33.2
-app_file: app.py
-pinned: false
-license: mit
-short_description: Science Talk Adventure Game
+# 🌱 Science Talk Adventure
+
+An interactive simulation game for preservice elementary teachers to practice facilitating equitable science discussions.
+
+## 🎯 Purpose
+
+This tool helps future teachers develop skills in:
+- **Equitable discourse facilitation** - including all student voices
+- **Cultural asset building** - honoring diverse knowledge systems  
+- **Scientific thinking promotion** - supporting authentic inquiry
+- **Classroom management** - managing participation fairly
+
+## 🎮 How to Play
+
+1. **Start a science talk** by typing what you'd say to begin the discussion
+2. **Read student responses** showing diverse perspectives and engagement levels
+3. **Choose your next teaching move** from the provided options
+4. **Get immediate feedback** on your choices and their impact
+5. **Track engagement** and see how your facilitation affects different students
+
+## 👥 Meet Your Students
+
+- **Maya**: Mexican-American, bilingual, has grandmother's gardening knowledge
+- **Jamal**: African-American, urban background, very curious and asks lots of questions  
+- **Aisha**: Somali-American, thoughtful observer, needs processing time
+- **Emma**: White suburban, enthusiastic about science, sometimes dominates discussions
+
+## 🎓 Learning Objectives
+
+Players will develop ability to:
+- Recognize and build on students' cultural knowledge
+- Create inclusive participation opportunities
+- Respond to diverse communication styles
+- Integrate NGSS 3-dimensional learning principles
+- Support multilingual learners in science
+
+## 🔧 Technical Details
+
+Built with:
+- **Gradio** for the web interface
+- **OpenRouter API** for AI-generated student responses
+- **Hugging Face Spaces** for hosting
+
+## 🚀 Getting Started
+
+Simply click the interface above and begin your first science talk!
+
+## 📚 Educational Context
+
+Based on research showing that elementary teachers often struggle with:
+- Confidence in science teaching
+- Building on diverse cultural knowledge
+- Creating equitable classroom discussions
+- Implementing NGSS standards effectively
+
+## 🔄 For Educators
+
+This tool is open source and free to use in teacher preparation programs. To adapt for your context:
+
+1. **Fork this Space** to customize scenarios
+2. **Modify student personas** to match your local community
+3. **Add new grade levels** or science topics
+4. **Integrate with your curriculum**
+
+## 📖 Citations
+
+If you use this tool in research or publication, please cite:
+
+```
+Science Talk Adventure: An AI-Supported Simulation for Developing Equitable Science Teaching Practices
+[Your Name], [Your Institution]
+Available at: [this URL]
+```
+
+## 🤝 Contributing
+
+We welcome contributions! Areas for development:
+- Additional grade level scenarios
+- More diverse student personas  
+- Enhanced assessment features
+- Multi-language support
+
+## 📧 Contact
+
+Questions or feedback? Contact [your email]
+
+## 📄 License
+
+MIT License - feel free to use, modify, and share!
+
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+*This tool is designed to supplement, not replace, field experiences with real students. The goal is to provide safe practice space for developing equitable teaching skills.*