diff --git a/README.md b/README.md
index 9de6d2a..676ad4f 100644
--- a/README.md
+++ b/README.md
@@ -1,72 +1,113 @@
-
+
+
+
+
+
+
+# Build web apps that embed AI coding CLIs
+
+BrowserCode is an open source project built on [BrowserPod](https://browserpod.io/), a serverless runtime with a POSIX filesystem, `bash`, `git`, `npm`, and live previews, all running client-side via WebAssembly.
+
+[](https://discord.gg/8ySMrQv6X)
+[](https://github.com/leaningtech/browsercode/issues)
+[](package.json)
+[](LICENSE.txt)
+[](https://npm.im/browserpod)
+
+[Try it live](https://browsercode.io) · [Quickstart](#quickstart) · [How it works](#how-it-works) · [Roadmap](#roadmap) · [BrowserPod docs](https://browserpod.io/docs)
+
+
-
-
-
-
-[](https://discord.gg/8ySMrQv6X)
-[](https://github.com/leaningtech/browsercode/issues)
-
-
-
Run AI coding CLIs in the browser
-
-
- The BrowserPod runtime to build projects that embed AI coding CLIs.
-
+
+
+
Table of contents
+## What is BrowserCode?
+
+BrowserCode is a runtime for AI coding CLIs. Using [BrowserPod](https://browserpod.io/), the POSIX filesystem, the dev server, and the network proxy all run **inside the user's browser tab** via WebAssembly. It boots instantly.
+
+This repo is the demo: a shell that boots [Claude Code](https://www.anthropic.com/claude-code) and [Gemini CLI](https://github.com/google-gemini/gemini-cli) (with [Codex](https://openai.com/codex) and [OpenCode](https://opencode.ai) on the way), each in its own route, each with a live preview pane fed by BrowserPod's portal function.
+
+## Quickstart
+
+### Use it
-- [What is BrowserCode?](#about)
-- [Quickstart](#quickstart)
-- [Breaking BrowserCode](#breaking-browsercode)
-- [Roadmap](#roadmap)
+Just open **[browsercode.io](https://browsercode.io)**. The default route boots Claude Code in your browser; switch CLIs from the sidebar or by visiting:
-What is BrowserCode?
+| Route | CLI |
+| --- | --- |
+| [`/claude`](https://browsercode.io/claude) | Claude Code |
+| [`/gemini`](https://browsercode.io/gemini) | Gemini CLI |
+| [`/codex`](https://browsercode.io/codex) | Codex *(coming soon)* |
+| [`/opencode`](https://browsercode.io/opencode) | OpenCode *(coming soon)* |
-BrowserCode is a browser runtime for AI coding CLIs. BrowserCode is a working example of [BrowserPod](https://browserpod.io/), it includes:
+Depending on your auth method, you may be asked to copy a code from a separate tab. After that, prompt the agent like you would on your laptop — except the filesystem it edits, the `npm install` it runs, and the dev server it spins up are all living in the same tab.
-- Node.js v22 running in the browser via WebAssembly
-- A browser-contained, POSIX-like filesystem
-- Command line tools: bash, git, npm
-- Browser sandbox isolation from the user's operating system
-- Restricted outbound networking
-- Instant previews over URL via BrowserPod's portal function
-- Support for Express.js, Svelte, Next, Nuxt and React (with Wasm overrides)
+### Run it locally
-BrowserCode 0.5.0 is our second beta release. This preview launches with an unmodified version of Claude Code (with Gemini available too) running completely client-side.
+```bash
+git clone https://github.com/leaningtech/browsercode.git
+cd browsercode
+npm install
+```
-Quickstart
+You'll need a BrowserPod API key (`VITE_API_KEY`) from [browserpod.io](https://browserpod.io/) before `npm run dev` will boot a Pod.
-
+## How it works
-1. Go to [browsercode.io](https://browsercode.io)
-2. BrowserCode will boot instantly, opening with a quick modal tutorial to guide you
-3. Claude Code will launch instantly
-4. Depending on your log-in option, you may be asked to authenticate your account by copying a code from a separate tab
-
+The shell does three things:
-Breaking BrowserCode
-This is BrowserCode beta. Don't be kind to it. Stretch it, bend it, find out what breaks. Here are a few walls you might hit:
+1. **Boots a Pod per route.** `/[tool]/+page.svelte` calls `bootCLI(tool)` from [src/lib/utils/main.ts](src/lib/utils/main.ts), which loads `@leaningtech/browserpod`, mounts the right disk image (e.g. `claude_20260506.ext2`), and runs the CLI's entrypoint inside the sandbox.
+2. **Wires a terminal.** `pod.createDefaultTerminal()` is bound to the `#console` element so the CLI's stdio renders in the page.
+3. **Surfaces previews via the portal.** When something inside the Pod starts a server, BrowserPod's `onPortal` callback fires with a public URL. The Portal pane embeds that URL, with copy-link and QR-code affordances.
-- At launch, Claude is prompted using a custom skill to help it understand that it is running in a custom environment. However, it may first attempt its default behaviour before referencing the file
-- BrowserCode doesn't yet support native binaries, for more information, see the [BrowserPod documentation](https://browserpod.io/docs/guides/native-binaries)
-- Networking over TCP isn't available
-- For maximum compatbility, please use a Chromium browser. Safari currently isn't supported
+Per-tool config — disk image, command, args, optional auth-redirect rewrite — lives in [src/lib/config/tools.ts](src/lib/config/tools.ts).
+## What's included
-Roadmap
+| | |
+|---|---|
+| **Node.js, in the browser** | A Node runtime compiled to Wasm with `bash`, `git`, `npm`, and standard coreutils. Files can persist via OPFS / IndexedDB. |
+| **Instant previews via portal URLs** | Any port a process opens inside the Pod gets a public preview URL through BrowserPod's portal. |
+| **Cross-origin isolated** | `COOP`/`COEP`/`CORP` headers required by BrowserPod, configured in [_headers](_headers) and [vite.config.ts](vite.config.ts). |
+| **Frameworks supported** | Express, Next, Nuxt, and React work out of the box (with Wasm overrides — see below). |
+
+## Project layout
+
+```text
+browsercode/
+├── src/
+│ ├── routes/ # one route per CLI: /claude, /gemini, ...
+│ └── lib/
+│ ├── components/ # Terminal, Portal, Sidebar, Stepper, UtilityBar
+│ ├── config/tools.ts # CLI registry + per-tool BrowserPod config
+│ └── utils/main.ts # bootCLI() — mounts the Pod and runs the CLI
+├── static/
+│ ├── project/
+│ │ ├── claude/CLAUDE.md # shipped into the Pod for Claude Code
+│ │ └── gemini/GEMINI.md # shipped into the Pod for Gemini CLI
+│ └── readme/ # README assets
+├── _headers # COOP/COEP/CORP for cross-origin isolation
+└── vite.config.ts # same headers, mirrored for dev
+```
+
+## Breaking BrowserCode
+
+This is BrowserCode's second beta. Don't be kind to it. Stretch it, bend it, find out what breaks. A few walls you might hit:
+
+- **The agent may ignore its primer on the first turn.** The `CLAUDE.md` / `GEMINI.md` shipped into the Pod tells the model it's running on Wasm, but it can default to its usual behavior before consulting the file. Re-prompt or remind it.
+- **No native binaries.** See [Wasm overrides](#the-single-most-important-constraint-wasm-overrides) above. If `npm install` blows up, this is almost always why.
+- **Networking over TCP isn't available.**
+- **Use a Chromium browser for maximum compatibility.** Safari isn't supported.
+
+More edge cases live in the [BrowserPod docs](https://browserpod.io/docs/guides/native-binaries).
+
+## Roadmap
| | CLI | Status |
| :---: | --- | --- |
@@ -75,5 +116,20 @@ This is BrowserCode beta. Don't be kind to it. Stretch it, bend it, find out wha
| 
| **Codex** | 🚧 Coming soon |
| 
| **OpenCode** | 🚧 Coming soon |
+## Contributing
+
+Issues and PRs are welcome — especially: more CLI integrations, Wasm overrides we've missed, and reproductions for crashes/hangs you find while breaking it.
-(back to top)
+For platform-level questions (BrowserPod itself, disk images, native-binary support), the right venue is the [BrowserPod issue tracker](https://github.com/leaningtech/browserpod) and the [Discord](https://discord.gg/8ySMrQv6X).
+
+## License
+
+Apache-2.0 — see [LICENSE.txt](LICENSE.txt).
+
+---
+
+
+
+Built by [Leaning Technologies](https://leaningtech.com) on top of [BrowserPod](https://browserpod.io/).
+
+
diff --git a/static/readme/browsercode.webp b/static/readme/browsercode.webp
new file mode 100644
index 0000000..52530be
Binary files /dev/null and b/static/readme/browsercode.webp differ
diff --git a/static/readme/screenshot-hero.webp b/static/readme/screenshot-hero.webp
new file mode 100644
index 0000000..21c5cd2
Binary files /dev/null and b/static/readme/screenshot-hero.webp differ