diff --git a/README.md b/README.md
index 03e81b5fb9..588e768795 100644
--- a/README.md
+++ b/README.md
@@ -1,28 +1,85 @@
 # T3 Code
 
-T3 Code is a minimal web GUI for coding agents. Currently Codex-first, with Claude Code support coming soon.
+[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![GitHub Stars](https://img.shields.io/github/stars/pingdotgg/t3code?style=flat&logo=github)](https://github.com/pingdotgg/t3code/stargazers)
+[![GitHub Issues](https://img.shields.io/github/issues/pingdotgg/t3code?style=flat&logo=github)](https://github.com/pingdotgg/t3code/issues)
 
-## How to use
+A minimal web GUI for coding agents. Currently Codex-first, with Claude Code support coming soon.
+
+## ✨ Features
+
+- **Minimal Web Interface** - Clean, focused GUI for interacting with coding agents
+- **Codex Integration** - Built with OpenAI Codex support as the primary coding agent
+- **Desktop Application** - Native desktop app available for enhanced experience
+- **CLI Support** - Quick start via npx command
+- **Multiple Runtime Modes** - Flexible runtime configurations for different use cases
+
+## 🚀 Quick Start
+
+### Prerequisites
 
 > [!WARNING]
 > You need to have [Codex CLI](https://github.com/openai/codex) installed and authorized for T3 Code to work.
 
+### Installation
+
+#### Option 1: NPX (Recommended for quick testing)
+
 ```bash
 npx t3
 ```
 
-You can also just install the desktop app. It's cooler.
+#### Option 2: Desktop Application
+
+Download and install the desktop app from the [Releases page](https://github.com/pingdotgg/t3code/releases) for the best experience.
+
+## 📖 Documentation
+
+Comprehensive documentation is available in the `.docs` folder:
+
+- [Quick Start Guide](.docs/quick-start.md)
+- [Architecture Overview](.docs/architecture.md)
+- [Runtime Modes](.docs/runtime-modes.md)
+- [Workspace Layout](.docs/workspace-layout.md)
+- [Provider Architecture](.docs/provider-architecture.md)
+- [Prerequisites](.docs/codex-prerequisites.md)
+- [Available Scripts](.docs/scripts.md)
+
+## ⚠️ Project Status
+
+**This project is in early development.** Please expect:
+- Potential bugs and instability
+- Breaking changes between versions
+- Limited feature set
+
+## 🤝 Contributing
+
+We are currently not accepting contributions as the project is in early development. However, if you're interested in contributing:
+
+1. Read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening any issues or PRs
+2. Join our [Discord community](https://discord.gg/jn4EGJjrvv) for support and discussions
+3. Check existing [issues](https://github.com/pingdotgg/t3code/issues) before creating new ones
+
+### Issue Templates
+
+When reporting issues, please use the appropriate template:
+- [Bug Report](.github/ISSUE_TEMPLATE/bug_report.yml)
+- [Feature Request](.github/ISSUE_TEMPLATE/feature_request.yml)
 
-Install the [desktop app from the Releases page](https://github.com/pingdotgg/t3code/releases)
+## 🛠️ Development
 
-## Some notes
+This project uses TypeScript and includes automated CI/CD workflows for:
+- Continuous Integration
+- Pull Request size monitoring
+- Issue labeling
 
-We are very very early in this project. Expect bugs.
+## 📄 License
 
-We are not accepting contributions yet.
+License information not specified. Please check the repository for license details.
 
-## If you REALLY want to contribute still.... read this first
+## 💬 Support
 
-Read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening an issue or PR.
+Need help? Join our [Discord community](https://discord.gg/jn4EGJjrvv) for support and discussions.
 
-Need support? Join the [Discord](https://discord.gg/jn4EGJjrvv).
+---
+*Documentation improved by [Codec8](https://codec8.com) — AI-powered docs for GitHub repos. [Generate docs for your repo →](https://codec8.com)*
\ No newline at end of file