diff --git a/README.md b/README.md
index 7c56c4c..b2f0c47 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,120 @@
 # lmc
 
-To install dependencies:
+A Bun-based CLI tool for LLM chats with terminal native streaming.
+
+## Features
+
+- **Streaming markdown rendering** — incremental rendering with syntax highlighting
+- **Conversation persistence** — chat history saved to JSON
+- **Model configuration** — persist model preferences to JSON
+- **Reasoning display** — thinking tokens rendered _in style_ on stderr
+- **Usage stats** — input/output tokens and elapsed time after each response
+- **TTY-aware** — automatically disables markdown rendering when output is piped
+- **Text-to-speech** — `ttsc` sub-command for streaming TTS via Kokoro model
+
+## Requirements
+
+- [Bun](https://bun.com) v1.3+
+- [uv](https://docs.astral.sh/uv/) — only for `ttsc` (text-to-speech)
+
+## Installation
 
 ```bash
 bun install
+bun build:js
+bun link
+
+# For ttsc only
+cp -r tts ~/.ttsc
 ```
 
-To run:
+_Package to come later_
+
+## Usage
+
+### Chat (lmc)
 
 ```bash
-bun run index.ts
+lmc [options] <prompt...>
 ```
 
-This project was created using `bun init` in bun v1.3.11. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+| Flag         | Short | Type    | Description                                       |
+| ------------ | ----- | ------- | ------------------------------------------------- |
+| `--new`      | `-n`  | boolean | Start a new conversation (clear history)          |
+| `--model`    | `-m`  | string  | Set model name for this session                   |
+| `--save`     | `-s`  | boolean | Save the specified model (--model) as the default |
+| `--plain`    | —     | boolean | Disable markdown rendering (plain text output)    |
+| `--plainOut` | —     | boolean | Disable markdown rendering for stdout only        |
+| `--plainErr` | —     | boolean | Disable markdown rendering for stderr only        |
+
+**Examples:**
+
+```bash
+lmc --new "Introduce yourself."              # New conversation
+lmc "What is TypeScript?"                    # Continue most recent chat
+lmc -m llama3 "Explain quantum computing"    # Chat with specific model
+lmc --model llama3 --save                    # Set default model
+lmc --plain "Plain text output"              # No markdown rendering
+```
+
+### Text-to-Speech (ttsc)
+
+```bash
+echo "text" | ttsc [options]
+```
+
+| Flag     | Short | Type    | Description                                              |
+| -------- | ----- | ------- | -------------------------------------------------------- |
+| `--wait` | `-w`  | boolean | Wait for all processing before exiting (don't auto-play) |
+
+**Examples:**
+
+```bash
+echo "Hello, world!" | ttsc
+echo "Read this aloud" | ttsc --wait
+```
+
+Requires: [uv](https://docs.astral.sh/uv/)
+
+Wants:
+
+- `mpv` for playback
+- `sox` for wav merging with `--wait`
+
+## Development
+
+```bash
+bun run dev      # dev run
+bun run prod     # run bundled output
+bun run check    # biome lint + format + organize imports
+```
+
+## Architecture
+
+```
+index.ts                — LMC entry point, orchestration
+tts.ts                  — TTSC entry point, orchestration
+src/render/index.ts     — Renderer class: streams LLM response, buffers markdown
+src/render/markdown.ts  — renderMarkdown(): syntax-highlighted markdown via Bun.markdown + Shiki
+src/conversation/       — Conversation persistence
+src/config/             — App config persistence
+tts/                    — TTS python stub (Kokoro pipeline)
+out/                    — Bundled output (index.js, tts.js)
+```
+
+## Configuration
+
+- **Conversation history:** `~/.lmc_convo.json`
+- **Model config:** `~/.lmc_config.json`
+- **TTS files:** `~/.ttsc/`
+
+## Dependencies
+
+| Package                     | Purpose                                   |
+| --------------------------- | ----------------------------------------- |
+| `ai` (Vercel AI SDK)        | Streaming text/usage                      |
+| `@ai-sdk/openai-compatible` | OpenAI-compatible API client              |
+| `shiki`                     | Syntax highlighting (kanagawa-wave theme) |
+| `cli-table3`                | ASCII table rendering                     |
+| `chalk`                     | Terminal string styling                   |
+| `terminal-link`             | Clickable terminal hyperlinks             |