diff --git a/README.md b/README.md
index e215bc4..216c487 100644
--- a/README.md
+++ b/README.md
@@ -1,36 +1,84 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# 🦞 OpenClaw Voice
+
+A walkie-talkie style voice + text chat interface for [OpenClaw](https://openclaw.ai), built with Next.js 16. Speak into your microphone, get a spoken response back. No cloud APIs required.
+
+---
+
+## Features
+
+- 🎙 **Push-to-talk** — hold the button to record, release to send
+- 👂 **Live Mode** — toggle on to speak hands-free; messages send automatically at the end of each utterance
+- 💬 **Text chat** — standard text input alongside voice
+- 🔊 **Text-to-speech** — OpenClaw's responses are read aloud via the device's built-in TTS (Web Speech API)
+- 🧠 **On-device Whisper** — audio from PTT is transcribed locally via `@huggingface/transformers` running server-side on Node.js — no OpenAI key needed
+- 📡 **Streaming responses** — OpenClaw replies stream in token by token
+- 🔒 **No external API keys** — only your local OpenClaw instance is required
+
+---
+
+## Tech Stack
+
+| Layer | Technology |
+|---|---|
+| Framework | Next.js 16 (App Router) |
+| Styling | Tailwind CSS |
+| Transcription (PTT) | Whisper tiny.en via `@huggingface/transformers` |
+| Transcription (Live) | Web Speech API (`SpeechRecognition`) |
+| Text-to-speech | Web Speech API (`SpeechSynthesis`) |
+| AI backend | OpenClaw (local, `localhost:18789`) |
+| Streaming | Server-Sent Events (SSE) |
+
+---
+
+## Prerequisites
+
+- **Node.js 18+**
+- **OpenClaw** installed and running locally
+
+### Install & configure OpenClaw
+
+```bash
+npm install -g openclaw@latest
+openclaw onboard --install-daemon
+
+# Disable auth for local development
+openclaw config set gateway.auth.mode none
+openclaw gateway restart
+openclaw gateway status
+```
+
+---
 
 ## Getting Started
 
-First, run the development server:
+### 1. Clone and install
+
+```bash
+git clone https://github.com/your-username/openclaw-voice.git
+cd openclaw-voice
+npm install
+```
+
+### 2. Configure environment
+
+Create `.env.local` in the project root:
+
+```env
+OPENCLAW_BASE_URL=http://localhost:18789
+OPENCLAW_AGENT_ID=main
+```
+
+No API keys needed.
+
+### 3. Run the dev server
 
 ```bash
 npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
 ```
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+Open [http://localhost:3000](http://localhost:3000).
 
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+---
 
-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+## Project Structure
 
-## Learn More
-
-To learn more about Next.js, take a look at the following resources:
-
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
-
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
-
-## Deploy on Vercel
-
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
-
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.