docs: readme

1 files changed, 41 insertions, 23 deletions

diff --git a/README.md b/README.md
index 8f455309d..d2ba219e4 100644
--- a/README.md
+++ b/README.md
@@ -2,39 +2,57 @@
 
 AI coding agent, built for the terminal.
 
-Note: version 0.1.x is a full rewrite and we do not have proper documentation for it yet. Should have this out week of June 17th 2025
+⚠️ **Note:** version 0.1.x is a full rewrite and we do not have proper documentation for it yet. Should have this out week of June 17th 2025 📚
 
-## Installation
+### Installation
 
-If you have a previous version of opencode < 0.1.x installed you might have to remove it first.
-
-### Curl
-
-```
+```bash
+# YOLO
 curl -fsSL https://opencode.ai/install | bash
+
+# Package managers
+npm i -g opencode-ai@latest        # or bun/pnpm/yarn
+brew install sst/tap/opencode      # macOS
+paru -S opencode-bin               # Arch Linux
 ```
 
-### NPM
+> **Note:** Remove previous versions < 0.1.x first if installed
 
-```
-npm i -g opencode-ai@latest
-bun i -g opencode-ai@latest
-pnpm i -g opencode-ai@latest
-yarn global add opencode-ai@latest
-```
+### Providers
 
-### Brew
+The recommended approach is to sign up for claude pro or max and do `opencode auth login` and select Anthropic. It is the most cost effective way to use this tool.
 
-```
-brew install sst/tap/opencode
-```
+Additionally opencode is powered by the provider list at [models.dev](https://models.dev) so you can use `opencode auth login` to configure api keys for any provider you'd like to use. This is stored in `~/.local/share/opencode/auth.json`
 
-### AUR
+```bash
+$ opencode auth login
 
+┌  Add credential
+│
+◆  Select provider
+│  ● Anthropic (recommended)
+│  ○ OpenAI
+│  ○ Google
+│  ○ Amazon Bedrock
+│  ○ Azure
+│  ○ DeepSeek
+│  ○ Groq
+│  ...
+└
 ```
-paru -S opencode-bin
-```
 
-## Usage
+The models.dev dataset is also used to detect common environment variables like `OPENAI_API_KEY` to autoload that provider.
+
+If there are additional providers you want to use you can submit a PR to the [models.dev repo](https://github.com/sst/models.dev). If configuring just for yourself check out the Config section below
+
+### Project Config
+
+Project configuration is optional. You can place an `opencode.json` file in the root of your repo and it will be loaded.
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/schemas/opencode.json"
+}
+```
 
-We are working on proper keybinds - right now it's the various function keys press F1 to see them
+#### MCP