diff --git a/README.md b/README.md
index 4bf13fb2f..cff324c6b 100644
--- a/README.md
+++ b/README.md
@@ -185,6 +185,29 @@ nanobot agent
 - Want to run nanobot in chat apps like Telegram, Discord, WeChat or Feishu? See [Chat Apps](./docs/chat-apps.md)
 - Want Docker or Linux service deployment? See [Deployment](./docs/deployment.md)
 
+## 🧪 WebUI (Development)
+
+> [!NOTE]
+> The WebUI development workflow currently requires a source checkout and is not yet shipped together with the official packaged release. See [WebUI Document](./webui/README.md) for full WebUI development docs, build steps, and release notes.
+
+<p align="center">
+  <img src="images/nanobot_webui.png" alt="nanobot webui preview" width="900">
+</p>
+
+**1. Start the gateway**
+
+```bash
+nanobot gateway
+```
+
+**2. Start the webui dev server**
+
+```bash
+cd webui
+bun install
+bun run dev
+```
+
 ## 🏗️ Architecture
 
 <p align="center">
diff --git a/images/nanobot_webui.png b/images/nanobot_webui.png
new file mode 100644
index 000000000..b074281d6
Binary files /dev/null and b/images/nanobot_webui.png differ
diff --git a/webui/README.md b/webui/README.md
index 6d3e554cb..9d3591d22 100644
--- a/webui/README.md
+++ b/webui/README.md
@@ -1,45 +1,90 @@
 # nanobot webui
 
-The browser front-end for `nanobot web`. Built with Vite + React 18 +
-TypeScript + Tailwind 3 + shadcn/ui. Talks to the gateway over the WebSocket
-multiplex protocol; session metadata comes from the embedded REST surface on
-the same port.
+The browser front-end for `nanobot web`. It is built with Vite + React 18 +
+TypeScript + Tailwind 3 + shadcn/ui, talks to the gateway over the WebSocket
+multiplex protocol, and reads session metadata from the embedded REST surface
+on the same port.
+
+For the project overview, install guide, and general docs map, see the root
+[`README.md`](../README.md).
+
+## Current status
+
+> [!NOTE]
+> The standalone WebUI development workflow currently requires a source
+> checkout.
+>
+> WebUI changes in the GitHub repository may land before they are included in
+> the next packaged release, so source installs and published package versions
+> are not yet guaranteed to move in lockstep.
 
 ## Layout
 
-```
+```text
 webui/                 source tree (this directory)
-nanobot/web/dist/      build output, shipped in the Python wheel
+nanobot/web/dist/      build output consumed by `nanobot web`
 ```
 
-## Develop
+## Develop from source
+
+### 1. Install nanobot from source
+
+From the repository root:
+
+```bash
+pip install -e .
+```
+
+### 2. Start the gateway
+
+In one terminal:
+
+```bash
+nanobot gateway
+```
+
+### 3. Start the WebUI dev server
+
+In another terminal:
 
 ```bash
 cd webui
 bun install            # npm install also works
-bun run dev            # http://127.0.0.1:5173 (proxies /api /webui /auth -> 8765)
+bun run dev
 ```
 
-In a separate shell, start the gateway with the WebSocket channel:
+Then open `http://127.0.0.1:5173`.
 
-```bash
-uv run nanobot gateway        # or `nanobot web` once you've built once
-```
+By default, the dev server proxies `/api`, `/webui`, `/auth`, and WebSocket
+traffic to `http://127.0.0.1:8765`.
 
-If the gateway listens on a non-default port, point the dev server at it:
+If your gateway listens on a non-default port, point the dev server at it:
 
 ```bash
 NANOBOT_API_URL=http://127.0.0.1:9000 bun run dev
 ```
 
-## Build
+## Build for packaged runtime
 
 ```bash
-bun run build   # writes ../nanobot/web/dist (consumed by `nanobot web`)
+cd webui
+bun run build
 ```
 
+This writes the production assets to `../nanobot/web/dist`, which is the
+directory served by `nanobot web` and bundled into the Python wheel.
+
+If you are cutting a release, run the build before packaging so the published
+wheel contains the current WebUI assets.
+
 ## Test
 
 ```bash
-bun run test    # vitest, jsdom-style happy-dom environment
+cd webui
+bun run test
 ```
+
+## Acknowledgements
+
+- [`agent-chat-ui`](https://github.com/langchain-ai/agent-chat-ui) for UI and
+  interaction inspiration across the chat surface.