diff --git a/.gitignore b/.gitignore
index 2382ed5..d086f9e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,4 +2,16 @@
 **/target/
 *.wasm
 .env
+.env*
 .claude/
+ui/dist/
+*.rs.bk
+*.rlib
+*.prof*
+.idea/
+*.log
+.DS_Store
+Thumbs.db
+*.tmp
+*.swp
+.vscode/
diff --git a/CLAUDE.md b/CLAUDE.md
index 9f038c7..26850ea 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -14,11 +14,12 @@ A secure, WASM-sandboxed AI agent runtime written in Rust. The "infrastructure l
 cargo check                        # type-check (fast feedback loop)
 cargo build                        # debug build
 cargo build --release              # release build (~21MB, LTO + strip)
+cargo run -- onboard               # first-time setup (secure API key entry)
 cargo run -- status                # smoke test
 cargo run -- gateway --port 7200   # start gateway on loopback (no auth needed)
 cargo run -- gateway --bind 0.0.0.0 --token my-secret  # non-loopback requires token
 cargo run -- plugin load ./path/to/plugin.wasm          # load a WASM plugin
-cargo test                         # run tests (none yet)
+cargo test                         # run all tests (134 tests)
 cargo clippy                       # lint (fix all non-dead-code warnings)
 cargo fmt                          # format (canonical style, zero config)
 cargo fmt --check                  # check formatting without modifying
@@ -27,6 +28,23 @@ RUST_LOG=debug cargo run -- gateway # enable debug logging
 
 Dead-code warnings from `cargo clippy` are expected until modules are wired together. All other clippy warnings should be zero.
 
+### Building the Chat UI (WASM)
+
+```bash
+# Prerequisites (one-time)
+rustup target add wasm32-unknown-unknown
+cargo install trunk
+
+# Build the Leptos frontend
+trunk build                        # dev build (fast, no wasm-opt)
+trunk build --release              # release build (smaller bundle)
+
+# The output goes to ui/dist/ which is embedded in the server binary via rust-embed.
+# After rebuilding the UI, recompile the server: cargo build
+```
+
+The Chat UI is a Leptos 0.7 CSR app in `ui/`. It compiles to WASM and is embedded in the server binary. The gateway serves it at `/`.
+
 ### Building the echo plugin (WASM)
 
 ```bash
@@ -40,6 +58,8 @@ Plugin crates use `crate-type = ["cdylib"]` and depend on `extism-pdk`.
 ## Architecture
 
 ```
+Browser (http://localhost:7200) → ui/ (Leptos WASM, embedded via rust-embed)
+                                      ↓ WebSocket
 Client (WebSocket) → gateway/ (axum, auth, JSON-RPC)
                         → router/ (hierarchical session routing)
                             → agent/ (LLM streaming: Anthropic + OpenAI SSE)
@@ -59,8 +79,9 @@ Client (WebSocket) → gateway/ (axum, auth, JSON-RPC)
 
 ### Module Relationships
 
-- `main.rs` — CLI entry point (clap). Creates `gateway::Config` and calls `gateway::run()` or `sandbox::load_plugin()`.
-- `gateway/server.rs` — Owns `AppState` which holds `SessionRouter` and `Arc<RwLock<PluginHost>>`. Starts axum server, handles WebSocket upgrade, runs auth-then-message-loop per connection.
+- `main.rs` — CLI entry point (clap). Handles `onboard` (API key setup via `run_onboard()`), `gateway` (starts server), `plugin` (loads WASM plugins), and `status` commands.
+- `gateway/server.rs` — Owns `AppState` which holds `SessionRouter`, `PluginHost`, `SessionStore`, `MemoryEngine`, `ExoclawConfig`, and per-session locks. Starts axum server, handles WebSocket upgrade, runs auth-then-message-loop per connection. Serves embedded UI at `/` via `rust-embed`.
+- `secrets.rs` — Credential storage. Stores API keys at `~/.exoclaw/credentials/{provider}.key` with mode 0600. Functions: `store_api_key()`, `load_api_key()`. Provider whitelist prevents path traversal.
 - `gateway/protocol.rs` — JSON-RPC dispatch. Accesses `AppState` to query plugins and router. Methods: `ping`, `status`, `chat.send` (stub), `plugin.list`.
 - `gateway/auth.rs` — `verify_connect()` parses first WS message for token, compares with `subtle::ConstantTimeEq`. Returns true if no token configured (loopback mode).
 - `router/mod.rs` — `SessionRouter` holds `Vec<Binding>` and `HashMap<String, SessionState>`. `resolve()` walks bindings in priority order, creates/updates sessions keyed as `{agent_id}:{channel}:{account}:{peer}`.
@@ -76,8 +97,11 @@ Client (WebSocket) → gateway/ (axum, auth, JSON-RPC)
 - **axum 0.8**: WebSocket `.close()` requires `use futures::SinkExt`.
 - **Auth enforcement**: Non-loopback bind requires `--token` or `EXOCLAW_TOKEN` env var. Loopback skips auth entirely (returns true with no token check).
 - **Plugin instances**: Created fresh per `call()` invocation for isolation — the `PluginEntry` stores the `Manifest`, not a live `Plugin`.
-- **Rust edition 2024**: Both the main crate and echo-plugin use `edition = "2024"`.
-- **No tests exist yet**. `dev-dependencies` has `tokio-test` ready.
+- **Rust edition 2024**: All workspace crates use `edition = "2024"`.
+- **Cargo workspace**: Root crate `exoclaw` (server binary) + `ui/` crate `exoclaw-ui` (Leptos WASM frontend). They share a `Cargo.lock` and `target/` directory.
+- **Leptos 0.7 CSR**: The UI crate uses client-side rendering (`features = ["csr"]`). Built with `trunk build` which produces `ui/dist/` (index.html + WASM + JS glue). The server binary embeds these files via `rust-embed`.
+- **UI asset embedding**: `rust-embed` embeds `ui/dist/` at compile time. After changing UI code, rebuild with `trunk build` then `cargo build` to re-embed.
+- **Credential storage**: API keys stored at `~/.exoclaw/credentials/{provider}.key` (mode 0600). Resolution: env var > credential file > None. Config file never contains the key.
 
 ## Design Decisions
 
@@ -102,3 +126,10 @@ See `specs/001-core-runtime/` for the full feature specification:
 - `data-model.md` — Entity schemas and relationships
 - `contracts/jsonrpc-spec.md` — WebSocket JSON-RPC protocol
 - `quickstart.md` — Getting started guide
+
+## Active Technologies
+- Rust 2024 edition, Leptos 0.7 CSR + axum 0.8, gloo-net (WASM WebSocket client), pulldown-cmark (WASM markdown), rpassword 7, rust-embed (static asset embedding)
+- Filesystem only — `~/.exoclaw/credentials/` for keys, `~/.exoclaw/config.toml` for config
+
+## Recent Changes
+- 002-onboard-chat-ui: Added Leptos 0.7 CSR chat UI (trunk + rust-embed), onboarding CLI, gloo-net WebSocket client, pulldown-cmark markdown rendering, 14 integration tests
diff --git a/Cargo.lock b/Cargo.lock
index 6eac23a..0b32357 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -103,6 +103,17 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "any_spawner"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41058deaa38c9d9dd933d6d238d825227cffa668e2839b52879f6619c63eee3b"
+dependencies = [
+ "futures",
+ "thiserror 2.0.18",
+ "wasm-bindgen-futures",
+]
+
 [[package]]
 name = "anyhow"
 version = "1.0.101"
@@ -115,6 +126,17 @@ version = "1.4.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c3d036a3c4ab069c7b410a2ce876bd74808d2d0888a82667669f8e783a898bf1"
 
+[[package]]
+name = "async-lock"
+version = "3.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "290f7f2596bd5b78a9fec8088ccd89180d7f9f55b94b0576823bbbdc72ee8311"
+dependencies = [
+ "event-listener",
+ "event-listener-strategy",
+ "pin-project-lite",
+]
+
 [[package]]
 name = "async-nats"
 version = "0.38.0"
@@ -168,6 +190,36 @@ version = "1.1.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1505bd5d3d116872e7271a6d4e16d81d0c8570876c8de68093a09ac269d8aac0"
 
+[[package]]
+name = "attribute-derive"
+version = "0.10.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05832cdddc8f2650cc2cc187cc2e952b8c133a48eb055f35211f61ee81502d77"
+dependencies = [
+ "attribute-derive-macro",
+ "derive-where",
+ "manyhow",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "attribute-derive-macro"
+version = "0.10.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0a7cdbbd4bd005c5d3e2e9c885e6fa575db4f4a3572335b974d8db853b6beb61"
+dependencies = [
+ "collection_literals",
+ "interpolator",
+ "manyhow",
+ "proc-macro-utils",
+ "proc-macro2",
+ "quote",
+ "quote-use",
+ "syn",
+]
+
 [[package]]
 name = "autocfg"
 version = "1.5.0"
@@ -286,6 +338,12 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "camino"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e629a66d692cb9ff1a1c664e41771b3dcaf961985a9774c0eb0bd1b51cf60a48"
+
 [[package]]
 name = "cap-fs-ext"
 version = "3.4.5"
@@ -490,18 +548,101 @@ dependencies = [
  "thiserror 2.0.18",
 ]
 
+[[package]]
+name = "codee"
+version = "0.3.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a9dbbdc4b4d349732bc6690de10a9de952bd39ba6a065c586e26600b6b0b91f5"
+dependencies = [
+ "serde",
+ "serde_json",
+ "thiserror 2.0.18",
+]
+
+[[package]]
+name = "collection_literals"
+version = "1.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2550f75b8cfac212855f6b1885455df8eaee8fe8e246b647d69146142e016084"
+
 [[package]]
 name = "colorchoice"
 version = "1.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b05b61dc5112cbb17e4b6cd61790d9845d13888356391624cbe7e41efeac1e75"
 
+[[package]]
+name = "concurrent-queue"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4ca0197aee26d1ae37445ee532fefce43251d24cc7c166799f4d46817f1d3973"
+dependencies = [
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "config"
+version = "0.15.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b30fa8254caad766fc03cb0ccae691e14bf3bd72bfff27f72802ce729551b3d6"
+dependencies = [
+ "convert_case 0.6.0",
+ "pathdiff",
+ "serde_core",
+ "toml 0.9.11+spec-1.1.0",
+ "winnow",
+]
+
 [[package]]
 name = "const-oid"
 version = "0.9.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c2459377285ad874054d797f3ccebf984978aa39129f6eafde5cdc8315b612f8"
 
+[[package]]
+name = "const_format"
+version = "0.2.35"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7faa7469a93a566e9ccc1c73fe783b4a65c274c5ace346038dca9c39fe0030ad"
+dependencies = [
+ "const_format_proc_macros",
+]
+
+[[package]]
+name = "const_format_proc_macros"
+version = "0.2.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d57c2eccfb16dbac1f4e61e206105db5820c9d26c3c472bc17c774259ef7744"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-xid",
+]
+
+[[package]]
+name = "const_str_slice_concat"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f67855af358fcb20fac58f9d714c94e2b228fe5694c1c9b4ead4a366343eda1b"
+
+[[package]]
+name = "convert_case"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ec182b0ca2f35d8fc196cf3404988fd8b8c739a4d270ff118a398feb0cbec1ca"
+dependencies = [
+ "unicode-segmentation",
+]
+
+[[package]]
+name = "convert_case"
+version = "0.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bb402b8d4c85569410425650ce3eddc7d698ed96d39a73f941b08fb63082f1e7"
+dependencies = [
+ "unicode-segmentation",
+]
+
 [[package]]
 name = "core-foundation"
 version = "0.9.4"
@@ -796,6 +937,20 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "dashmap"
+version = "6.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5041cc499144891f3790297212f32a74fb938e5136a14943f338ef9e0ae276cf"
+dependencies = [
+ "cfg-if",
+ "crossbeam-utils",
+ "hashbrown 0.14.5",
+ "lock_api",
+ "once_cell",
+ "parking_lot_core",
+]
+
 [[package]]
 name = "data-encoding"
 version = "2.10.0"
@@ -832,6 +987,17 @@ dependencies = [
  "serde_core",
 ]
 
+[[package]]
+name = "derive-where"
+version = "1.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ef941ded77d15ca19b40374869ac6000af1c9f2a4c0f3d4c70926287e6364a8f"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "digest"
 version = "0.10.7"
@@ -874,6 +1040,18 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "drain_filter_polyfill"
+version = "0.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "669a445ee724c5c69b1b06fe0b63e70a1c84bc9bb7d9696cd4f4e3ec45050408"
+
+[[package]]
+name = "dyn-clone"
+version = "1.0.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d0881ea181b1df73ff77ffaaf9c7544ecc11e82fba9b5f27b262a3c73a332555"
+
 [[package]]
 name = "ed25519"
 version = "2.2.3"
@@ -902,6 +1080,16 @@ version = "1.15.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "48c757948c5ede0e46177b7add2e67155f70e33c07fea8284df6576da70b3719"
 
+[[package]]
+name = "either_of"
+version = "0.1.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "216d23e0ec69759a17f05e1c553f3a6870e5ec73420fbb07807a6f34d5d1d5a4"
+dependencies = [
+ "paste",
+ "pin-project-lite",
+]
+
 [[package]]
 name = "embedded-io"
 version = "0.4.0"
@@ -939,6 +1127,27 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "event-listener"
+version = "5.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e13b66accf52311f30a0db42147dadea9850cb48cd070028831ae5f5d4b856ab"
+dependencies = [
+ "concurrent-queue",
+ "parking",
+ "pin-project-lite",
+]
+
+[[package]]
+name = "event-listener-strategy"
+version = "0.5.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8be9f3dfaaffdae2972880079a491a1a8bb7cbed0b8dd7a347f668b4150a3b93"
+dependencies = [
+ "event-listener",
+ "pin-project-lite",
+]
+
 [[package]]
 name = "exoclaw"
 version = "0.1.0"
@@ -952,8 +1161,11 @@ dependencies = [
  "criterion",
  "extism",
  "futures",
+ "mime_guess",
  "reqwest",
  "rmp-serde",
+ "rpassword",
+ "rust-embed",
  "serde",
  "serde_json",
  "subtle",
@@ -970,6 +1182,25 @@ dependencies = [
  "uuid",
 ]
 
+[[package]]
+name = "exoclaw-ui"
+version = "0.1.0"
+dependencies = [
+ "futures",
+ "gloo-net",
+ "js-sys",
+ "leptos",
+ "leptos_meta",
+ "leptos_router",
+ "log",
+ "pulldown-cmark",
+ "serde",
+ "serde_json",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+ "web-sys",
+]
+
 [[package]]
 name = "extism"
 version = "1.13.0"
@@ -1168,6 +1399,7 @@ dependencies = [
  "futures-core",
  "futures-task",
  "futures-util",
+ "num_cpus",
 ]
 
 [[package]]
@@ -1249,6 +1481,15 @@ dependencies = [
  "version_check",
 ]
 
+[[package]]
+name = "getopts"
+version = "0.2.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cfe4fbac503b8d1f88e6676011885f34b7174f46e59956bba534ba83abded4df"
+dependencies = [
+ "unicode-width",
+]
+
 [[package]]
 name = "getrandom"
 version = "0.2.17"
@@ -1293,6 +1534,46 @@ version = "0.3.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0cc23270f6e1808e30a928bdc84dea0b9b4136a8bc82338574f23baf47bbd280"
 
+[[package]]
+name = "gloo-net"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c06f627b1a58ca3d42b45d6104bf1e1a03799df472df00988b6ba21accc10580"
+dependencies = [
+ "futures-channel",
+ "futures-core",
+ "futures-sink",
+ "gloo-utils",
+ "http",
+ "js-sys",
+ "pin-project",
+ "serde",
+ "serde_json",
+ "thiserror 1.0.69",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+ "web-sys",
+]
+
+[[package]]
+name = "gloo-utils"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b5555354113b18c547c1d3a98fbf7fb32a9ff4f6fa112ce823a21641a0ba3aa"
+dependencies = [
+ "js-sys",
+ "serde",
+ "serde_json",
+ "wasm-bindgen",
+ "web-sys",
+]
+
+[[package]]
+name = "guardian"
+version = "1.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "17e2ac29387b1aa07a1e448f7bb4f35b500787971e965b02842b900afa5c8f6f"
+
 [[package]]
 name = "h2"
 version = "0.4.13"
@@ -1323,6 +1604,12 @@ dependencies = [
  "zerocopy",
 ]
 
+[[package]]
+name = "hashbrown"
+version = "0.14.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e5274423e17b7c9fc20b6e7e208532f9b19825d82dfd615708b70edd83df41f1"
+
 [[package]]
 name = "hashbrown"
 version = "0.15.5"
@@ -1351,6 +1638,15 @@ version = "0.5.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "fc0fef456e4baa96da950455cd02c081ca953b141298e41db3fc7e36b1da849c"
 
+[[package]]
+name = "html-escape"
+version = "0.2.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6d1ad449764d627e22bfd7cd5e8868264fc9236e07c752972b4080cd351cb476"
+dependencies = [
+ "utf8-width",
+]
+
 [[package]]
 name = "http"
 version = "1.4.0"
@@ -1396,6 +1692,20 @@ version = "1.0.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9"
 
+[[package]]
+name = "hydration_context"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d35485b3dcbf7e044b8f28c73f04f13e7b509c2466fd10cb2a8a447e38f8a93a"
+dependencies = [
+ "futures",
+ "once_cell",
+ "or_poisoned",
+ "pin-project-lite",
+ "serde",
+ "throw_error",
+]
+
 [[package]]
 name = "hyper"
 version = "1.8.1"
@@ -1621,6 +1931,12 @@ dependencies = [
  "serde_core",
 ]
 
+[[package]]
+name = "interpolator"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "71dd52191aae121e8611f1e8dc3e324dd0dd1dee1e6dd91d10ee07a3cfb4d9d8"
+
 [[package]]
 name = "io-extras"
 version = "0.18.4"
@@ -1752,6 +2068,181 @@ version = "0.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "09edd9e8b54e49e587e4f6295a7d29c3ea94d469cb40ab8ca70b288248a81db2"
 
+[[package]]
+name = "leptos"
+version = "0.7.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "26b8731cb00f3f0894058155410b95c8955b17273181d2bc72600ab84edd24f1"
+dependencies = [
+ "any_spawner",
+ "cfg-if",
+ "either_of",
+ "futures",
+ "hydration_context",
+ "leptos_config",
+ "leptos_dom",
+ "leptos_hot_reload",
+ "leptos_macro",
+ "leptos_server",
+ "oco_ref",
+ "or_poisoned",
+ "paste",
+ "reactive_graph",
+ "rustc-hash",
+ "send_wrapper",
+ "serde",
+ "serde_qs",
+ "server_fn",
+ "slotmap",
+ "tachys",
+ "thiserror 2.0.18",
+ "throw_error",
+ "typed-builder",
+ "typed-builder-macro",
+ "wasm-bindgen",
+ "web-sys",
+]
+
+[[package]]
+name = "leptos_config"
+version = "0.7.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5bae3e0ead5a7a814c8340eef7cb8b6cba364125bd8174b15dc9fe1b3cab7e03"
+dependencies = [
+ "config",
+ "regex",
+ "serde",
+ "thiserror 2.0.18",
+ "typed-builder",
+]
+
+[[package]]
+name = "leptos_dom"
+version = "0.7.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f89d4eb263bd5a9e7c49f780f17063f15aca56fd638c90b9dfd5f4739152e87d"
+dependencies = [
+ "js-sys",
+ "or_poisoned",
+ "reactive_graph",
+ "send_wrapper",
+ "tachys",
+ "wasm-bindgen",
+ "web-sys",
+]
+
+[[package]]
+name = "leptos_hot_reload"
+version = "0.7.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e80219388501d99b246f43b6e7d08a28f327cdd34ba630a35654d917f3e1788e"
+dependencies = [
+ "anyhow",
+ "camino",
+ "indexmap",
+ "parking_lot",
+ "proc-macro2",
+ "quote",
+ "rstml",
+ "serde",
+ "syn",
+ "walkdir",
+]
+
+[[package]]
+name = "leptos_macro"
+version = "0.7.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e621f8f5342b9bdc93bb263b839cee7405027a74560425a2dabea9de7952b1fd"
+dependencies = [
+ "attribute-derive",
+ "cfg-if",
+ "convert_case 0.7.1",
+ "html-escape",
+ "itertools 0.14.0",
+ "leptos_hot_reload",
+ "prettyplease",
+ "proc-macro-error2",
+ "proc-macro2",
+ "quote",
+ "rstml",
+ "server_fn_macro",
+ "syn",
+ "uuid",
+]
+
+[[package]]
+name = "leptos_meta"
+version = "0.7.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "448a6387e9e2cccbb756f474a54e36a39557127a3b8e46744b6ef6372b50f575"
+dependencies = [
+ "futures",
+ "indexmap",
+ "leptos",
+ "once_cell",
+ "or_poisoned",
+ "send_wrapper",
+ "wasm-bindgen",
+ "web-sys",
+]
+
+[[package]]
+name = "leptos_router"
+version = "0.7.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4168ead6a9715daba953aa842795cb2ad81b6e011a15745bd3d1baf86f76de95"
+dependencies = [
+ "any_spawner",
+ "either_of",
+ "futures",
+ "gloo-net",
+ "js-sys",
+ "leptos",
+ "leptos_router_macro",
+ "once_cell",
+ "or_poisoned",
+ "reactive_graph",
+ "send_wrapper",
+ "tachys",
+ "thiserror 2.0.18",
+ "url",
+ "wasm-bindgen",
+ "web-sys",
+]
+
+[[package]]
+name = "leptos_router_macro"
+version = "0.7.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e31197af38d209ffc5d9f89715381c415a1570176f8d23455fbe00d148e79640"
+dependencies = [
+ "proc-macro-error2",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "leptos_server"
+version = "0.7.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "66985242812ec95e224fb48effe651ba02728beca92c461a9464c811a71aab11"
+dependencies = [
+ "any_spawner",
+ "base64",
+ "codee",
+ "futures",
+ "hydration_context",
+ "or_poisoned",
+ "reactive_graph",
+ "send_wrapper",
+ "serde",
+ "serde_json",
+ "server_fn",
+ "tachys",
+]
+
 [[package]]
 name = "libc"
 version = "0.2.180"
@@ -1774,6 +2265,12 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "linear-map"
+version = "1.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bfae20f6b19ad527b550c223fddc3077a547fc70cda94b9b566575423fd303ee"
+
 [[package]]
 name = "linux-raw-sys"
 version = "0.4.15"
@@ -1887,6 +2384,16 @@ version = "0.3.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6877bb514081ee2a7ff5ef9de3281f14a4dd4bceac4c09388074a6b5df8a139a"
 
+[[package]]
+name = "mime_guess"
+version = "2.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f7c44f8e672c00fe5308fa235f821cb4198414e1c77935c1ab6948d3fd78550e"
+dependencies = [
+ "mime",
+ "unicase",
+]
+
 [[package]]
 name = "miniz_oxide"
 version = "0.8.9"
@@ -1925,6 +2432,12 @@ dependencies = [
  "tempfile",
 ]
 
+[[package]]
+name = "next_tuple"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "60993920e071b0c9b66f14e2b32740a4e27ffc82854dcd72035887f336a09a28"
+
 [[package]]
 name = "nkeys"
 version = "0.4.5"
@@ -1973,6 +2486,16 @@ dependencies = [
  "autocfg",
 ]
 
+[[package]]
+name = "num_cpus"
+version = "1.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "91df4bbde75afed763b708b7eee1e8e7651e02d97f6d5dd763e89367e957b23b"
+dependencies = [
+ "hermit-abi",
+ "libc",
+]
+
 [[package]]
 name = "object"
 version = "0.37.3"
@@ -1985,6 +2508,16 @@ dependencies = [
  "memchr",
 ]
 
+[[package]]
+name = "oco_ref"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed0423ff9973dea4d6bd075934fdda86ebb8c05bdf9d6b0507067d4a1226371d"
+dependencies = [
+ "serde",
+ "thiserror 2.0.18",
+]
+
 [[package]]
 name = "once_cell"
 version = "1.21.3"
@@ -2053,6 +2586,18 @@ dependencies = [
  "vcpkg",
 ]
 
+[[package]]
+name = "or_poisoned"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8c04f5d74368e4d0dfe06c45c8627c81bd7c317d52762d118fb9b3076f6420fd"
+
+[[package]]
+name = "parking"
+version = "2.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f38d5652c16fde515bb1ecef450ab0f6a219d619a7274976324d5e377f7dceba"
+
 [[package]]
 name = "parking_lot"
 version = "0.12.5"
@@ -2076,6 +2621,18 @@ dependencies = [
  "windows-link",
 ]
 
+[[package]]
+name = "paste"
+version = "1.0.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "57c0d7b74b563b49d38dae00a0c37d4d6de9b432382b2892f0574ddcae73fd0a"
+
+[[package]]
+name = "pathdiff"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df94ce210e5bc13cb6651479fa48d14f601d9858cfe0467f43ae157023b938d3"
+
 [[package]]
 name = "pem-rfc7468"
 version = "0.7.0"
@@ -2209,6 +2766,16 @@ dependencies = [
  "zerocopy",
 ]
 
+[[package]]
+name = "prettyplease"
+version = "0.2.37"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "479ca8adacdd7ce8f1fb39ce9ecccbfe93a3f1344b3d0d97f20bc0196208f62b"
+dependencies = [
+ "proc-macro2",
+ "syn",
+]
+
 [[package]]
 name = "proc-macro-crate"
 version = "3.4.0"
@@ -2218,6 +2785,28 @@ dependencies = [
  "toml_edit 0.23.10+spec-1.0.0",
 ]
 
+[[package]]
+name = "proc-macro-error-attr2"
+version = "2.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "96de42df36bb9bba5542fe9f1a054b8cc87e172759a1868aa05c1f3acc89dfc5"
+dependencies = [
+ "proc-macro2",
+ "quote",
+]
+
+[[package]]
+name = "proc-macro-error2"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "11ec05c52be0a07b08061f7dd003e7d7092e0472bc731b4af7bb1ef876109802"
+dependencies = [
+ "proc-macro-error-attr2",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "proc-macro-utils"
 version = "0.10.0"
@@ -2238,6 +2827,19 @@ dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "proc-macro2-diagnostics"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "af066a9c399a26e020ada66a034357a868728e72cd426f3adcd35f80d88d88c8"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+ "version_check",
+ "yansi",
+]
+
 [[package]]
 name = "prost"
 version = "0.14.3"
@@ -2261,6 +2863,25 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "pulldown-cmark"
+version = "0.12.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f86ba2052aebccc42cbbb3ed234b8b13ce76f75c3551a303cb2bcffcff12bb14"
+dependencies = [
+ "bitflags",
+ "getopts",
+ "memchr",
+ "pulldown-cmark-escape",
+ "unicase",
+]
+
+[[package]]
+name = "pulldown-cmark-escape"
+version = "0.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "007d8adb5ddab6f8e3f491ac63566a7d5002cc7ed73901f72057943fa71ae1ae"
+
 [[package]]
 name = "pulley-interpreter"
 version = "37.0.3"
@@ -2348,6 +2969,28 @@ dependencies = [
  "proc-macro2",
 ]
 
+[[package]]
+name = "quote-use"
+version = "0.8.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9619db1197b497a36178cfc736dc96b271fe918875fbf1344c436a7e93d0321e"
+dependencies = [
+ "quote",
+ "quote-use-macros",
+]
+
+[[package]]
+name = "quote-use-macros"
+version = "0.8.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "82ebfb7faafadc06a7ab141a6f67bcfb24cb8beb158c6fe933f2f035afa99f35"
+dependencies = [
+ "proc-macro-utils",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "r-efi"
 version = "5.3.0"
@@ -2433,6 +3076,55 @@ dependencies = [
  "crossbeam-utils",
 ]
 
+[[package]]
+name = "reactive_graph"
+version = "0.1.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "76a0ccddbc11a648bd09761801dac9e3f246ef7641130987d6120fced22515e6"
+dependencies = [
+ "any_spawner",
+ "async-lock",
+ "futures",
+ "guardian",
+ "hydration_context",
+ "or_poisoned",
+ "pin-project-lite",
+ "rustc-hash",
+ "send_wrapper",
+ "serde",
+ "slotmap",
+ "thiserror 2.0.18",
+ "web-sys",
+]
+
+[[package]]
+name = "reactive_stores"
+version = "0.1.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "aadc7c19e3a360bf19cd595d2dc8b58ce67b9240b95a103fbc1317a8ff194237"
+dependencies = [
+ "guardian",
+ "itertools 0.14.0",
+ "or_poisoned",
+ "paste",
+ "reactive_graph",
+ "reactive_stores_macro",
+ "rustc-hash",
+]
+
+[[package]]
+name = "reactive_stores_macro"
+version = "0.1.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "221095cb028dc51fbc2833743ea8b1a585da1a2af19b440b3528027495bf1f2d"
+dependencies = [
+ "convert_case 0.7.1",
+ "proc-macro-error2",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "redox_syscall"
 version = "0.5.18"
@@ -2576,6 +3268,77 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "rpassword"
+version = "7.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "66d4c8b64f049c6721ec8ccec37ddfc3d641c4a7fca57e8f2a89de509c73df39"
+dependencies = [
+ "libc",
+ "rtoolbox",
+ "windows-sys 0.59.0",
+]
+
+[[package]]
+name = "rstml"
+version = "0.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "61cf4616de7499fc5164570d40ca4e1b24d231c6833a88bff0fe00725080fd56"
+dependencies = [
+ "derive-where",
+ "proc-macro2",
+ "proc-macro2-diagnostics",
+ "quote",
+ "syn",
+ "syn_derive",
+ "thiserror 2.0.18",
+]
+
+[[package]]
+name = "rtoolbox"
+version = "0.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a7cc970b249fbe527d6e02e0a227762c9108b2f49d81094fe357ffc6d14d7f6f"
+dependencies = [
+ "libc",
+ "windows-sys 0.52.0",
+]
+
+[[package]]
+name = "rust-embed"
+version = "8.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "04113cb9355a377d83f06ef1f0a45b8ab8cd7d8b1288160717d66df5c7988d27"
+dependencies = [
+ "rust-embed-impl",
+ "rust-embed-utils",
+ "walkdir",
+]
+
+[[package]]
+name = "rust-embed-impl"
+version = "8.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "da0902e4c7c8e997159ab384e6d0fc91c221375f6894346ae107f47dd0f3ccaa"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "rust-embed-utils",
+ "syn",
+ "walkdir",
+]
+
+[[package]]
+name = "rust-embed-utils"
+version = "8.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5bcdef0be6fe7f6fa333b1073c949729274b05f123a0ad7efcb8efd878e5c3b1"
+dependencies = [
+ "mime_guess",
+ "sha2",
+ "walkdir",
+]
+
 [[package]]
 name = "rustc-demangle"
 version = "0.1.27"
@@ -2796,6 +3559,15 @@ dependencies = [
  "serde_core",
 ]
 
+[[package]]
+name = "send_wrapper"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cd0b0ec5f1c1ca621c432a25813d8d60c88abe6d3e08a3eb9cf37d97a0fe3d73"
+dependencies = [
+ "futures-core",
+]
+
 [[package]]
 name = "serde"
 version = "1.0.228"
@@ -2859,6 +3631,17 @@ dependencies = [
  "serde_core",
 ]
 
+[[package]]
+name = "serde_qs"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cd34f36fe4c5ba9654417139a9b3a20d2e1de6012ee678ad14d240c22c78d8d6"
+dependencies = [
+ "percent-encoding",
+ "serde",
+ "thiserror 1.0.69",
+]
+
 [[package]]
 name = "serde_repr"
 version = "0.1.20"
@@ -2900,6 +3683,60 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "server_fn"
+version = "0.7.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8d05a9e3fd8d7404985418db38c6617cc793a1a27f398d4fbc9dfe8e41b804e6"
+dependencies = [
+ "bytes",
+ "const_format",
+ "dashmap",
+ "futures",
+ "gloo-net",
+ "http",
+ "js-sys",
+ "once_cell",
+ "pin-project-lite",
+ "send_wrapper",
+ "serde",
+ "serde_json",
+ "serde_qs",
+ "server_fn_macro_default",
+ "thiserror 2.0.18",
+ "throw_error",
+ "url",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+ "wasm-streams",
+ "web-sys",
+ "xxhash-rust",
+]
+
+[[package]]
+name = "server_fn_macro"
+version = "0.7.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "504b35e883267b3206317b46d02952ed7b8bf0e11b2e209e2eb453b609a5e052"
+dependencies = [
+ "const_format",
+ "convert_case 0.6.0",
+ "proc-macro2",
+ "quote",
+ "syn",
+ "xxhash-rust",
+]
+
+[[package]]
+name = "server_fn_macro_default"
+version = "0.7.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eb8b274f568c94226a8045668554aace8142a59b8bca5414ac5a79627c825568"
+dependencies = [
+ "server_fn_macro",
+ "syn",
+]
+
 [[package]]
 name = "sha1"
 version = "0.10.6"
@@ -2981,6 +3818,15 @@ version = "0.4.12"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
 
+[[package]]
+name = "slotmap"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bdd58c3c93c3d278ca835519292445cb4b0d4dc59ccfdf7ceadaab3f8aeb4038"
+dependencies = [
+ "version_check",
+]
+
 [[package]]
 name = "smallvec"
 version = "1.15.1"
@@ -3039,6 +3885,18 @@ dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "syn_derive"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cdb066a04799e45f5d582e8fc6ec8e6d6896040d00898eb4e6a835196815b219"
+dependencies = [
+ "proc-macro-error2",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "sync_wrapper"
 version = "1.0.2"
@@ -3096,6 +3954,40 @@ dependencies = [
  "winx",
 ]
 
+[[package]]
+name = "tachys"
+version = "0.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f66c3b70c32844a6f1e2943c72a33ebb777ad6acbeb20d1329d62e3a7806d6ec"
+dependencies = [
+ "any_spawner",
+ "async-trait",
+ "const_str_slice_concat",
+ "drain_filter_polyfill",
+ "dyn-clone",
+ "either_of",
+ "futures",
+ "html-escape",
+ "indexmap",
+ "itertools 0.14.0",
+ "js-sys",
+ "linear-map",
+ "next_tuple",
+ "oco_ref",
+ "once_cell",
+ "or_poisoned",
+ "parking_lot",
+ "paste",
+ "reactive_graph",
+ "reactive_stores",
+ "rustc-hash",
+ "send_wrapper",
+ "slotmap",
+ "throw_error",
+ "wasm-bindgen",
+ "web-sys",
+]
+
 [[package]]
 name = "target-lexicon"
 version = "0.13.4"
@@ -3173,6 +4065,15 @@ dependencies = [
  "cfg-if",
 ]
 
+[[package]]
+name = "throw_error"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e4ef8bf264c6ae02a065a4a16553283f0656bd6266fc1fcb09fd2e6b5e91427b"
+dependencies = [
+ "pin-project-lite",
+]
+
 [[package]]
 name = "time"
 version = "0.3.47"
@@ -3589,18 +4490,50 @@ dependencies = [
  "utf-8",
 ]
 
+[[package]]
+name = "typed-builder"
+version = "0.20.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cd9d30e3a08026c78f246b173243cf07b3696d274debd26680773b6773c2afc7"
+dependencies = [
+ "typed-builder-macro",
+]
+
+[[package]]
+name = "typed-builder-macro"
+version = "0.20.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3c36781cc0e46a83726d9879608e4cf6c2505237e263a8eb8c24502989cfdb28"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "typenum"
 version = "1.19.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "562d481066bde0658276a35467c4af00bdc6ee726305698a55b86e61d7ad82bb"
 
+[[package]]
+name = "unicase"
+version = "2.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dbc4bc3a9f746d862c45cb89d705aa10f187bb96c76001afab07a0d35ce60142"
+
 [[package]]
 name = "unicode-ident"
 version = "1.0.22"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9312f7c4f6ff9069b165498234ce8be658059c6728633667c526e27dc2cf1df5"
 
+[[package]]
+name = "unicode-segmentation"
+version = "1.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f6ccf251212114b54433ec949fd6a7841275f9ada20dddd2f29e9ceea4501493"
+
 [[package]]
 name = "unicode-width"
 version = "0.2.2"
@@ -3666,6 +4599,12 @@ version = "0.7.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "09cc8ee72d2a9becf2f2febe0205bbed8fc6615b7cb429ad062dc7b7ddd036a9"
 
+[[package]]
+name = "utf8-width"
+version = "0.1.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1292c0d970b54115d14f2492fe0170adf21d68a1de108eebc51c1df4f346a091"
+
 [[package]]
 name = "utf8_iter"
 version = "1.0.4"
@@ -4612,6 +5551,18 @@ version = "0.6.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9edde0db4769d2dc68579893f2306b26c6ecfbe0ef499b013d731b7b9247e0b9"
 
+[[package]]
+name = "xxhash-rust"
+version = "0.8.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fdd20c5420375476fbd4394763288da7eb0cc0b8c11deed431a91562af7335d3"
+
+[[package]]
+name = "yansi"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cfe53a6657fd280eaa890a3bc59152892ffa3e30101319d168b781ed6529b049"
+
 [[package]]
 name = "yoke"
 version = "0.8.1"
diff --git a/Cargo.toml b/Cargo.toml
index 5ed9487..181de4a 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,3 +1,6 @@
+[workspace]
+members = [".", "ui"]
+
 [package]
 name = "exoclaw"
 version = "0.1.0"
@@ -34,6 +37,7 @@ async-nats = "0.38"
 
 # CLI
 clap = { version = "4", features = ["derive", "env"] }
+rpassword = "7"
 
 # Logging
 tracing = "0.1"
@@ -45,6 +49,10 @@ async-trait = "0.1"
 # URL parsing (for webhook proxy host validation)
 url = "2"
 
+# Embedded static assets (serves UI WASM bundle)
+rust-embed = { version = "8", features = ["mime-guess"] }
+mime_guess = "2"
+
 # Utilities
 uuid = { version = "1", features = ["v4"] }
 chrono = { version = "0.4", features = ["serde"] }
diff --git a/README.md b/README.md
index 385daca..d3aa182 100644
--- a/README.md
+++ b/README.md
@@ -73,6 +73,9 @@ git clone https://github.com/exoclaw/exoclaw.git
 cd exoclaw
 cargo build --release
 
+# First-time setup (secure prompt for provider + API key)
+cargo run -- onboard
+
 # Start the gateway (loopback, no auth required)
 cargo run -- gateway
 
@@ -86,6 +89,12 @@ cargo run -- status
 cargo run -- plugin load ./plugins/telegram.wasm
 ```
 
+`onboard` stores the API key in `~/.exoclaw/credentials/{provider}.key` with file mode `600`. API key resolution order:
+
+1. `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` environment variable (highest priority)
+2. Credential file at `~/.exoclaw/credentials/{provider}.key`
+3. `api_key` field in config file (not recommended)
+
 The gateway binds to `127.0.0.1:7200` by default. When binding to a non-loopback address, an auth token is required (via `--token` or `EXOCLAW_TOKEN` env var).
 
 ## Project status
diff --git a/examples/config.toml b/examples/config.toml
index 47e6d4f..2a35755 100644
--- a/examples/config.toml
+++ b/examples/config.toml
@@ -13,6 +13,7 @@ provider = "anthropic"                  # "anthropic" | "openai"
 model = "claude-sonnet-4-5-20250929"    # model identifier
 max_tokens = 4096                       # max tokens per LLM response
 # api_key: set via ANTHROPIC_API_KEY or OPENAI_API_KEY env var
+#          or run `exoclaw onboard` to save key in ~/.exoclaw/credentials/{provider}.key
 # system_prompt = "You are a helpful assistant."
 # soul_path = "~/.exoclaw/soul.md"      # personality document (~500 tokens)
 # tools = ["echo", "web-search"]        # plugin names this agent can use
diff --git a/examples/echo-plugin/Cargo.lock b/examples/echo-plugin/Cargo.lock
new file mode 100644
index 0000000..69ac322
--- /dev/null
+++ b/examples/echo-plugin/Cargo.lock
@@ -0,0 +1,380 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "anyhow"
+version = "1.0.101"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5f0e0fee31ef5ed1ba1316088939cea399010ed7731dba877ed44aeb407a75ea"
+
+[[package]]
+name = "autocfg"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"
+
+[[package]]
+name = "base64"
+version = "0.22.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
+
+[[package]]
+name = "bytemuck"
+version = "1.25.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c8efb64bd706a16a1bdde310ae86b351e4d21550d98d056f22f8a7f7a2183fec"
+
+[[package]]
+name = "bytes"
+version = "1.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e748733b7cbc798e1434b6ac524f0c1ff2ab456fe201501e6497c8417a4fc33"
+
+[[package]]
+name = "echo-plugin"
+version = "0.1.0"
+dependencies = [
+ "extism-pdk",
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "either"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "48c757948c5ede0e46177b7add2e67155f70e33c07fea8284df6576da70b3719"
+
+[[package]]
+name = "equivalent"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
+
+[[package]]
+name = "extism-convert"
+version = "1.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4f6612b4e92559eeb4c2dac88a53ee8b4729bea64025befcdeb2b3677e62fc1d"
+dependencies = [
+ "anyhow",
+ "base64",
+ "bytemuck",
+ "extism-convert-macros",
+ "prost",
+ "rmp-serde",
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "extism-convert-macros"
+version = "1.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "525831f1f15079a7c43514905579aac10f90fee46bc6353b683ed632029dd945"
+dependencies = [
+ "manyhow",
+ "proc-macro-crate",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "extism-manifest"
+version = "1.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e60e36345a96ad0d74adfca64dc22d93eb4979ab15a6c130cded5e0585f31b10"
+dependencies = [
+ "base64",
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "extism-pdk"
+version = "1.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "352fcb5a66eb74145a1c4a01f2bd15d59c62c85be73aac8471880c65b26b798f"
+dependencies = [
+ "anyhow",
+ "base64",
+ "extism-convert",
+ "extism-manifest",
+ "extism-pdk-derive",
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "extism-pdk-derive"
+version = "1.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d086daea5fd844e3c5ac69ddfe36df4a9a43e7218cf7d1f888182b089b09806c"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.16.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "841d1cc9bed7f9236f321df977030373f4a4163ae1a7dbfe1a51a2c1a51d9100"
+
+[[package]]
+name = "indexmap"
+version = "2.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7714e70437a7dc3ac8eb7e6f8df75fd8eb422675fc7678aff7364301092b1017"
+dependencies = [
+ "equivalent",
+ "hashbrown",
+]
+
+[[package]]
+name = "itertools"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2b192c782037fadd9cfa75548310488aabdbf3d2da73885b31bd0abd03351285"
+dependencies = [
+ "either",
+]
+
+[[package]]
+name = "itoa"
+version = "1.0.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92ecc6618181def0457392ccd0ee51198e065e016d1d527a7ac1b6dc7c1f09d2"
+
+[[package]]
+name = "manyhow"
+version = "0.11.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b33efb3ca6d3b07393750d4030418d594ab1139cee518f0dc88db70fec873587"
+dependencies = [
+ "manyhow-macros",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "manyhow-macros"
+version = "0.11.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "46fce34d199b78b6e6073abf984c9cf5fd3e9330145a93ee0738a7443e371495"
+dependencies = [
+ "proc-macro-utils",
+ "proc-macro2",
+ "quote",
+]
+
+[[package]]
+name = "memchr"
+version = "2.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"
+
+[[package]]
+name = "num-traits"
+version = "0.2.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "proc-macro-crate"
+version = "3.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "219cb19e96be00ab2e37d6e299658a0cfa83e52429179969b0f0121b4ac46983"
+dependencies = [
+ "toml_edit",
+]
+
+[[package]]
+name = "proc-macro-utils"
+version = "0.10.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eeaf08a13de400bc215877b5bdc088f241b12eb42f0a548d3390dc1c56bb7071"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "smallvec",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "prost"
+version = "0.14.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d2ea70524a2f82d518bce41317d0fae74151505651af45faf1ffbd6fd33f0568"
+dependencies = [
+ "bytes",
+ "prost-derive",
+]
+
+[[package]]
+name = "prost-derive"
+version = "0.14.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "27c6023962132f4b30eb4c172c91ce92d933da334c59c23cddee82358ddafb0b"
+dependencies = [
+ "anyhow",
+ "itertools",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.44"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "21b2ebcf727b7760c461f091f9f0f539b77b8e87f2fd88131e7f1b433b3cece4"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rmp"
+version = "0.8.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4ba8be72d372b2c9b35542551678538b562e7cf86c3315773cae48dfbfe7790c"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "rmp-serde"
+version = "1.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72f81bee8c8ef9b577d1681a70ebbc962c232461e397b22c208c43c04b67a155"
+dependencies = [
+ "rmp",
+ "serde",
+]
+
+[[package]]
+name = "serde"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.149"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "83fc039473c5595ace860d8c4fafa220ff474b3fc6bfdb4293327f1a37e94d86"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "smallvec"
+version = "1.15.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67b1b7a3b5fe4f1376887184045fcf45c69e92af734b7aaddc05fb777b6fbd03"
+
+[[package]]
+name = "syn"
+version = "2.0.114"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d4d107df263a3013ef9b1879b0df87d706ff80f65a86ea879bd9c31f9b307c2a"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "toml_datetime"
+version = "0.7.5+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92e1cfed4a3038bc5a127e35a2d360f145e1f4b971b551a2ba5fd7aedf7e1347"
+dependencies = [
+ "serde_core",
+]
+
+[[package]]
+name = "toml_edit"
+version = "0.23.10+spec-1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "84c8b9f757e028cee9fa244aea147aab2a9ec09d5325a9b01e0a49730c2b5269"
+dependencies = [
+ "indexmap",
+ "toml_datetime",
+ "toml_parser",
+ "winnow",
+]
+
+[[package]]
+name = "toml_parser"
+version = "1.0.6+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a3198b4b0a8e11f09dd03e133c0280504d0801269e9afa46362ffde1cbeebf44"
+dependencies = [
+ "winnow",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.22"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9312f7c4f6ff9069b165498234ce8be658059c6728633667c526e27dc2cf1df5"
+
+[[package]]
+name = "winnow"
+version = "0.7.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a5364e9d77fcdeeaa6062ced926ee3381faa2ee02d3eb83a5c27a8825540829"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "zmij"
+version = "1.0.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3ff05f8caa9038894637571ae6b9e29466c1f4f829d26c9b28f869a29cbe3445"
diff --git a/specs/002-onboard-chat-ui/checklists/requirements.md b/specs/002-onboard-chat-ui/checklists/requirements.md
new file mode 100644
index 0000000..3e92096
--- /dev/null
+++ b/specs/002-onboard-chat-ui/checklists/requirements.md
@@ -0,0 +1,36 @@
+# Specification Quality Checklist: Onboarding & Built-in Chat UI
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-02-08
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- US1 (Onboarding) has partial implementation already on `main` branch (uncommitted) — spec captures the intended behavior
+- US2 (Chat UI) depends on 001-core-runtime's `chat.send` being wired end-to-end (currently stubbed)
+- Spec references 001-core-runtime SC-006 as the motivating gap
diff --git a/specs/002-onboard-chat-ui/contracts/routes.md b/specs/002-onboard-chat-ui/contracts/routes.md
new file mode 100644
index 0000000..e0b7723
--- /dev/null
+++ b/specs/002-onboard-chat-ui/contracts/routes.md
@@ -0,0 +1,78 @@
+# HTTP Routes: Onboarding & Chat UI
+
+**Feature**: `002-onboard-chat-ui`
+
+## New Routes
+
+### GET `/` — Leptos Chat Application
+
+Serves the Leptos-rendered chat page. In SSR mode, returns pre-rendered HTML with a WASM hydration script.
+
+**Response**: HTML document with inline Leptos app shell + `<script>` tag loading the WASM bundle from `/pkg/`.
+
+**No authentication required** — the chat page itself is public. Auth happens at the WebSocket layer when the user sends their first message.
+
+### GET `/pkg/*` — Static Assets (WASM bundle, JS glue)
+
+Served by `tower_http::services::ServeDir` from the `target/site/pkg/` directory.
+
+**Assets**:
+- `*.wasm` — compiled Leptos frontend
+- `*.js` — WASM glue code (generated by wasm-bindgen)
+- `*.css` — styles (if separated)
+
+**Cache headers**: `Cache-Control: public, max-age=31536000, immutable` (content-hashed filenames).
+
+## Existing Routes (Unchanged)
+
+### GET `/ws` — WebSocket JSON-RPC
+
+No changes. The Leptos frontend connects to this endpoint using `gloo-net::WebSocket`. The JSON-RPC protocol is identical whether the client is the chat UI, `websocat`, or a custom client.
+
+### GET `/health` — Health Check
+
+No changes.
+
+### POST `/webhook/{channel}` — Platform Webhooks
+
+No changes.
+
+## Route Registration Order
+
+```rust
+Router::new()
+    // 1. Custom routes first (take precedence)
+    .route("/ws", get(ws_handler))
+    .route("/health", get(health))
+    .route("/webhook/{channel}", post(webhook_handler))
+    // 2. Leptos routes (catches / and renders the app)
+    .leptos_routes(state, routes!(App))
+    // 3. Static assets
+    .fallback(ServeDir::new("target/site"))
+```
+
+## CLI Contract: `exoclaw onboard`
+
+Not an HTTP route — a CLI subcommand.
+
+```
+exoclaw onboard [--provider <anthropic|openai>]
+```
+
+**Interactive prompts** (when `--provider` not given):
+1. `Provider (anthropic/openai) [anthropic]:` — text input with default
+2. `Anthropic API key:` — hidden input (rpassword)
+
+**Exit codes**:
+- `0` — success, config and credentials written
+- `1` — validation error (empty key, invalid provider), filesystem error
+
+**Stdout on success**:
+```
+exoclaw onboarding
+This writes config to /home/user/.exoclaw/config.toml.
+Saved config to /home/user/.exoclaw/config.toml
+Saved API key to /home/user/.exoclaw/credentials/anthropic.key
+Configured provider=anthropic model=claude-sonnet-4-5-20250929
+Next: cargo run -- gateway
+```
diff --git a/specs/002-onboard-chat-ui/data-model.md b/specs/002-onboard-chat-ui/data-model.md
new file mode 100644
index 0000000..d07ca24
--- /dev/null
+++ b/specs/002-onboard-chat-ui/data-model.md
@@ -0,0 +1,109 @@
+# Data Model: Onboarding & Built-in Chat UI
+
+**Feature**: `002-onboard-chat-ui`
+**Date**: 2026-02-08
+
+## Entities
+
+### Credential File
+
+A filesystem artifact, not a runtime data structure.
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| provider | string | `"anthropic"` or `"openai"` — determines filename |
+| api_key | string | Raw API key value (plaintext) |
+| path | filesystem path | `~/.exoclaw/credentials/{provider}.key` |
+| permissions | unix mode | `0600` (owner read/write only) |
+| parent_dir_permissions | unix mode | `0700` (owner only) |
+
+**Lifecycle**:
+- Created by `exoclaw onboard`
+- Overwritten by re-running `exoclaw onboard`
+- Read at gateway startup by `config::resolve_api_key()`
+- Never read by the chat UI or any WASM plugin
+
+**Uniqueness**: One file per provider. Re-onboarding overwrites.
+
+### Chat UI State (Browser-side, Leptos Signals)
+
+Reactive state managed by Leptos in the browser. Not persisted.
+
+| Signal | Type | Description |
+|--------|------|-------------|
+| messages | `RwSignal<Vec<ChatMessage>>` | Conversation history displayed in the UI |
+| input_text | `RwSignal<String>` | Current text in the message input field |
+| is_streaming | `RwSignal<bool>` | Whether an LLM response is currently streaming |
+| is_connected | `RwSignal<bool>` | WebSocket connection status |
+| ws_connection | `Option<WebSocket>` | Active gloo-net WebSocket handle |
+| auth_token | `RwSignal<Option<String>>` | Token entered by user (if auth required) |
+| needs_auth | `RwSignal<bool>` | Whether to show the auth token prompt |
+
+### ChatMessage (UI-side)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| role | enum | `User` or `Assistant` or `Error` |
+| content | String | Raw text (user) or accumulated markdown (assistant) |
+| is_complete | bool | Whether streaming has finished for this message |
+
+**State transitions**:
+1. User sends message → `ChatMessage { role: User, content: input, is_complete: true }` added
+2. Stream starts → `ChatMessage { role: Assistant, content: "", is_complete: false }` added
+3. Tokens arrive → `content` appended token-by-token
+4. Stream ends → `is_complete = true`
+5. Error occurs → `ChatMessage { role: Error, content: error_msg, is_complete: true }` added
+
+## Relationships
+
+```
+Credential File ──reads──► config::resolve_api_key() ──provides──► AgentRunner
+                                                                        │
+Chat UI (Leptos) ──WebSocket──► /ws ──JSON-RPC──► gateway::protocol ────┘
+    │                                                    │
+    └── ChatMessage[]                                    └── Session (001-core-runtime)
+```
+
+- The Chat UI and Credential File are completely independent — the UI never reads credentials
+- The Chat UI connects to the same `/ws` endpoint as any other WebSocket client
+- Server-side session state (from 001-core-runtime) persists across UI page refreshes
+- The UI's `messages` signal is ephemeral — lost on refresh
+
+## Data Flow: Onboarding
+
+```
+User runs `exoclaw onboard`
+    │
+    ├─► prompt: provider selection (default: anthropic)
+    ├─► prompt: API key (hidden input via rpassword)
+    │
+    ├─► validate: key non-empty
+    │
+    ├─► write: ~/.exoclaw/credentials/{provider}.key  (0600)
+    ├─► write: ~/.exoclaw/config.toml                 (0600)
+    │       └── contains: provider, model, NO api_key
+    │
+    └─► print: next steps ("cargo run -- gateway")
+```
+
+## Data Flow: Chat UI Message
+
+```
+User types message, presses Enter
+    │
+    ├─► [if !is_connected] open WebSocket to /ws
+    │       └─► [if needs_auth] send {"token": "..."} as first message
+    │
+    ├─► set is_streaming = true, disable input
+    ├─► add User message to messages[]
+    ├─► send JSON-RPC: {"jsonrpc":"2.0","method":"chat.send","params":{"content":"..."}}
+    │
+    ├─► add empty Assistant message to messages[]
+    │
+    ├─► receive stream events:
+    │       ├── {"event":"text","data":"token"} → append to assistant message content
+    │       ├── {"event":"error","data":"..."} → add Error message
+    │       └── {"event":"done"} → mark assistant message complete
+    │
+    └─► set is_streaming = false, re-enable input
+```
diff --git a/specs/002-onboard-chat-ui/plan.md b/specs/002-onboard-chat-ui/plan.md
new file mode 100644
index 0000000..0391130
--- /dev/null
+++ b/specs/002-onboard-chat-ui/plan.md
@@ -0,0 +1,128 @@
+# Implementation Plan: Onboarding & Built-in Chat UI
+
+**Branch**: `002-onboard-chat-ui` | **Date**: 2026-02-08 | **Spec**: [spec.md](spec.md)
+**Input**: Feature specification from `/specs/002-onboard-chat-ui/spec.md`
+
+## Summary
+
+Add two UX essentials missing from the core runtime: (1) a CLI onboarding command (`exoclaw onboard`) that securely stores API keys with proper file permissions, and (2) a Leptos-based web chat interface served at `/` that lets users talk to their agent through a browser with streamed markdown responses. Together, these make SC-006 ("install to first message in 5 minutes") achievable.
+
+## Technical Context
+
+**Language/Version**: Rust 2024 edition (existing), Leptos 0.8 (new)
+**Primary Dependencies**: axum 0.8 (existing), leptos 0.8 + leptos_axum (new), gloo-net (new, WASM WebSocket client), pulldown-cmark (new, WASM markdown), rpassword 7 (already added in uncommitted code)
+**Storage**: Filesystem only — `~/.exoclaw/credentials/` for keys, `~/.exoclaw/config.toml` for config
+**Testing**: `cargo test` (existing), browser-based manual testing for UI
+**Target Platform**: Linux/macOS server (binary) + modern browsers (WASM)
+**Project Type**: Cargo workspace — server binary + Leptos UI lib crate
+**Performance Goals**: Chat page load < 500ms including WASM hydration, token rendering < 50ms overhead
+**Constraints**: No npm/JS build tools. Binary under 25MB (constitution). Leptos WASM bundle served from same process.
+**Scale/Scope**: Single-user localhost. Not multi-tenant.
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+| Principle | Status | Notes |
+|-----------|--------|-------|
+| I. Secure by Default | PASS | API keys stored with 0600 perms, never in config file, env var precedence. Chat UI uses existing WebSocket auth (constant-time token comparison). No new trust boundaries introduced. |
+| II. Cost-Aware by Architecture | PASS | No impact on token metering. Chat UI is a thin client — all metering/budgets enforced server-side. |
+| III. Simple Configuration | PASS | `exoclaw onboard` makes setup *simpler* than the constitution requires. Config file stays single TOML. |
+| IV. WASM-First Plugin Model | PASS | Chat UI is NOT a plugin — it's the host's own frontend. It compiles to browser WASM (wasm32-unknown-unknown) but runs in the browser, not in the Extism sandbox. No confusion with the plugin model. |
+| V. Performance Without Compromise | PASS | Server binary grows ~1-2 MB (well under 25MB). WASM bundle ~50-100KB gzipped. Page load < 500ms (SC-003). Token rendering overhead < 50ms via fine-grained reactivity (SC-004). Startup not affected. |
+| Development Workflow | MINOR CHANGE | Build command changes from `cargo build` to `cargo leptos build`. `cargo check/test/clippy/fmt` unchanged. CI needs `cargo install cargo-leptos`. |
+
+**Gate result**: PASS — no violations. Minor workflow change documented.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/002-onboard-chat-ui/
+├── plan.md              # This file
+├── spec.md              # Feature specification
+├── research.md          # Technology decisions
+├── data-model.md        # Entity schemas
+├── quickstart.md        # Getting started guide
+├── contracts/
+│   └── routes.md        # HTTP route contracts
+├── checklists/
+│   └── requirements.md  # Quality checklist
+└── tasks.md             # Task list (generated by /speckit.tasks)
+```
+
+### Source Code (repository root)
+
+```text
+Cargo.toml                    # Workspace root (converted from single crate)
+├── src/                      # Existing server binary (workspace member "exoclaw")
+│   ├── main.rs               # CLI: onboard, gateway, plugin, status
+│   ├── lib.rs                # Module exports
+│   ├── config.rs             # Config + save() + resolve_api_key() (partially done)
+│   ├── secrets.rs            # Credential store (partially done)
+│   ├── gateway/
+│   │   ├── server.rs         # axum server — add Leptos route integration here
+│   │   ├── protocol.rs       # JSON-RPC dispatch (unchanged)
+│   │   └── auth.rs           # Token verification (unchanged)
+│   ├── agent/                # LLM streaming (unchanged)
+│   ├── router/               # Session routing (unchanged)
+│   ├── sandbox/              # WASM plugin host (unchanged)
+│   ├── bus/                  # NATS (unchanged)
+│   ├── store/                # Session store (unchanged)
+│   ├── memory/               # Memory engine (unchanged)
+│   └── types.rs              # Shared types (unchanged)
+│
+├── ui/                       # NEW: Leptos frontend crate (workspace member "exoclaw-ui")
+│   ├── Cargo.toml            # leptos, gloo-net, pulldown-cmark, serde_json
+│   └── src/
+│       ├── lib.rs            # Crate root, re-exports
+│       ├── app.rs            # Root App component + Leptos router
+│       └── components/
+│           ├── mod.rs
+│           ├── chat.rs       # Main chat container (message list + input)
+│           ├── message.rs    # Single message bubble (markdown rendering)
+│           ├── input.rs      # Message input with send button + disable-while-streaming
+│           ├── auth_prompt.rs # Token entry dialog (shown when gateway requires auth)
+│           └── status.rs     # Connection status indicator
+│
+├── examples/echo-plugin/     # Existing (unchanged)
+├── examples/mock-channel/    # Existing (unchanged)
+├── tests/                    # Existing integration tests (unchanged)
+└── benches/                  # Existing benchmarks (unchanged)
+```
+
+**Structure Decision**: Cargo workspace with the existing server as root member and `ui/` as a separate library crate. This cleanly separates server-only dependencies (extism, async-nats, reqwest) from browser-only dependencies (gloo-net, web-sys) without fragile `#[cfg(feature)]` gating.
+
+## Complexity Tracking
+
+No constitution violations requiring justification.
+
+## Implementation Notes
+
+### US1: Onboarding (Partially Complete)
+
+The uncommitted code on `main` already implements most of US1:
+- `src/secrets.rs` — credential store with read/write/permissions, 2 unit tests
+- `src/main.rs` — `exoclaw onboard` CLI command with provider selection + rpassword input
+- `src/config.rs` — `save()`, `save_to_path()`, `resolve_path()`, `Serialize` derives, credential file fallback in `resolve_api_key()`
+- `Cargo.toml` — `rpassword = "7"` dependency
+
+**Remaining work for US1**: Tests for the full onboard flow (integration tests), verify re-onboard preserves unrelated config, update CLAUDE.md/README.
+
+### US2: Chat UI (New)
+
+Requires:
+1. Convert project to Cargo workspace
+2. Create `ui/` crate with Leptos components
+3. Integrate Leptos serving into `gateway/server.rs`
+4. WebSocket client in WASM (gloo-net → JSON-RPC)
+5. Markdown rendering (pulldown-cmark)
+6. Input disable-while-streaming behavior
+7. Auth token prompt
+8. Connection status / error display
+9. Update build tooling (`cargo-leptos`)
+
+### Dependencies Between Stories
+
+US1 (Onboarding) and US2 (Chat UI) are independent — they can be implemented in parallel. US2 depends on 001-core-runtime's `chat.send` being wired (currently stubbed), but the UI can be built and tested against the stub or a mock.
diff --git a/specs/002-onboard-chat-ui/quickstart.md b/specs/002-onboard-chat-ui/quickstart.md
new file mode 100644
index 0000000..4d10831
--- /dev/null
+++ b/specs/002-onboard-chat-ui/quickstart.md
@@ -0,0 +1,75 @@
+# Quickstart: Onboarding & Chat UI
+
+**Feature**: `002-onboard-chat-ui`
+
+## Prerequisites
+
+- Rust toolchain (rustup)
+- `wasm32-unknown-unknown` target: `rustup target add wasm32-unknown-unknown`
+- cargo-leptos: `cargo install cargo-leptos`
+- An API key from Anthropic or OpenAI
+
+## First-Time Setup
+
+```bash
+# Clone and build
+git clone https://github.com/exoclaw/exoclaw.git
+cd exoclaw
+cargo leptos build --release
+
+# Run onboarding (one-time)
+cargo run -- onboard
+# Select provider: anthropic (default) or openai
+# Enter your API key (hidden input)
+
+# Start the gateway
+cargo run -- gateway
+```
+
+## Open the Chat UI
+
+Navigate to `http://localhost:7200` in your browser. Type a message and press Enter.
+
+That's it. Three commands from clone to conversation:
+1. `cargo leptos build --release`
+2. `cargo run -- onboard`
+3. `cargo run -- gateway`
+
+## What Happened
+
+- `onboard` saved your API key to `~/.exoclaw/credentials/anthropic.key` (mode 0600)
+- `onboard` wrote a config to `~/.exoclaw/config.toml` (mode 0600, no key in file)
+- `gateway` loaded the config, resolved the key from the credential file, and started listening
+- The chat UI at `/` connects via WebSocket to `/ws` and sends JSON-RPC messages
+
+## Re-configuring
+
+```bash
+# Switch providers
+cargo run -- onboard --provider openai
+
+# Or use environment variables (takes precedence over credential file)
+ANTHROPIC_API_KEY=sk-ant-... cargo run -- gateway
+OPENAI_API_KEY=sk-... cargo run -- gateway
+```
+
+## Development Mode
+
+```bash
+# Hot-reload during frontend development
+cargo leptos watch
+
+# Server-only checks (no WASM rebuild)
+cargo check
+cargo test
+cargo clippy
+```
+
+## Non-Loopback (Remote Access)
+
+```bash
+# Bind to all interfaces with auth token
+cargo run -- gateway --bind 0.0.0.0 --token my-secret-token
+
+# The chat UI will prompt for the token when it loads
+```
diff --git a/specs/002-onboard-chat-ui/research.md b/specs/002-onboard-chat-ui/research.md
new file mode 100644
index 0000000..cfee8bd
--- /dev/null
+++ b/specs/002-onboard-chat-ui/research.md
@@ -0,0 +1,140 @@
+# Research: Onboarding & Built-in Chat UI
+
+**Feature**: `002-onboard-chat-ui`
+**Date**: 2026-02-08
+
+## Decision 1: Frontend Framework
+
+**Decision**: Leptos 0.7 CSR (client-side rendering) with trunk + rust-embed
+
+**Rationale**:
+- Fine-grained reactivity (SolidJS-style): only the text node updates when tokens stream in, no virtual DOM diffing
+- CSR approach avoids SSR complexity — trunk compiles to WASM, rust-embed serves static assets from the server binary
+- No `leptos_axum` dependency needed — axum serves pre-built WASM/HTML via a simple fallback route
+- Leptos 0.7 is the stable release compatible with Rust edition 2024
+
+**Alternatives considered**:
+- **Leptos 0.8 with leptos_axum (SSR)**: Originally planned but pivoted away — SSR adds complexity for a chat UI that doesn't need server-side rendering. CSR is simpler and keeps `cargo build/test/clippy` working normally.
+- **Dioxus 0.7**: Cross-platform (web + desktop + mobile) but virtual DOM overhead, not axum-native. Better for desktop apps.
+- **Yew**: Mature but momentum has slowed. Virtual DOM.
+- **Inline HTML/JS**: Zero build complexity (~150 lines JS) but no Rust type safety, poor markdown rendering, doesn't align with project's Rust-first philosophy.
+
+## Decision 2: Project Structure
+
+**Decision**: Cargo workspace with separate UI crate
+
+**Rationale**:
+- The existing `Cargo.toml` has heavy server-only dependencies (extism, async-nats, reqwest/rustls) that must NOT compile into the WASM bundle
+- A separate `ui/` crate cleanly separates browser code from server code without fragile `#[cfg(feature)]` gating on dozens of dependencies
+- `cargo-leptos` handles building both the server binary and the WASM frontend
+- The server crate imports the UI crate and serves it via `leptos_axum`
+
+**Alternatives considered**:
+- **Single-crate with features**: Simpler Cargo.toml but requires feature-gating every server-only dependency. Error-prone with 20+ deps.
+- **Full start-axum-workspace** (app + server + frontend): Overkill — exoclaw already has a well-structured server crate.
+
+**Workspace layout**:
+```
+Cargo.toml              # workspace root
+├── src/                 # existing exoclaw server (binary crate, workspace member)
+├── ui/                  # new Leptos frontend (lib crate, workspace member)
+│   ├── Cargo.toml
+│   └── src/
+│       ├── lib.rs
+│       ├── app.rs       # Root Leptos app component
+│       └── components/
+│           ├── chat.rs
+│           ├── message.rs
+│           └── auth_prompt.rs
+└── examples/echo-plugin/ # existing (stays independent)
+```
+
+## Decision 3: Build Tooling
+
+**Decision**: `trunk` for WASM builds + `rust-embed` for asset serving
+
+**Rationale**:
+- `trunk build` compiles the Leptos CSR app to WASM and produces `ui/dist/` (index.html + WASM + JS glue)
+- `rust-embed` embeds `ui/dist/` at compile time into the server binary — no separate asset directory needed at runtime
+- `cargo check`, `cargo clippy`, `cargo test`, `cargo fmt` still work independently for the server crate
+- Simpler than `cargo-leptos` which is designed for SSR setups
+
+**Impact on existing workflow**:
+- UI changes: `trunk build` then `cargo build` to re-embed assets
+- `cargo check` / `cargo test` / `cargo clippy` / `cargo fmt` → unchanged
+- CI needs `trunk` installed: `cargo install trunk`
+
+## Decision 4: WebSocket Client (Browser)
+
+**Decision**: `gloo-net` for WebSocket from Leptos WASM to gateway
+
+**Rationale**:
+- Idiomatic Rust bindings over `web_sys::WebSocket`
+- Works cleanly in `wasm32-unknown-unknown` target
+- Supports async read/write via futures streams
+- The gateway's existing `/ws` endpoint and JSON-RPC protocol stay unchanged
+- The Leptos frontend connects as a regular WebSocket client
+
+**Alternatives considered**:
+- **Leptos server functions (WebSocket mode)**: Designed for Leptos-specific RPC, not generic JSON-RPC. Would require adapting the protocol.
+- **Raw web-sys**: More verbose, no async ergonomics.
+
+## Decision 5: Markdown Rendering
+
+**Decision**: `pulldown-cmark` compiled to WASM
+
+**Rationale**:
+- Lightweight WASM footprint (smallest of the Rust markdown parsers)
+- CommonMark compliant — handles code blocks, bold, italic, lists, headers
+- Pure Rust, no C dependencies — compiles cleanly to `wasm32-unknown-unknown`
+- Widely used (21M+ downloads)
+
+**Alternatives considered**:
+- **comrak**: Full GitHub Flavored Markdown but ~200KB+ additional WASM size. Overkill for chat.
+- **markdown-rs**: Newer, good WASM support, but smaller community.
+
+**Syntax highlighting**: Use a lightweight WASM-compatible highlighter or CSS-only approach (e.g., `class="language-rust"` + a minimal CSS theme). Avoid heavy highlighters like `syntect` in WASM.
+
+## Decision 6: Serving Strategy
+
+**Decision**: rust-embed fallback route at `/`, existing WebSocket at `/ws`
+
+**Rationale**:
+- Register custom routes (`/ws`, `/health`, `/webhook/{channel}`) BEFORE the UI fallback
+- The axum `.fallback(get(ui_handler))` catches `/` and all unmatched paths (SPA routing)
+- `ui_handler` serves files from the embedded `ui/dist/` assets, falling back to `index.html`
+- Custom handlers take precedence over the fallback
+
+**Route order**:
+```
+Router::new()
+    .route("/ws", get(ws_handler))            // Existing JSON-RPC WebSocket
+    .route("/health", get(health))            // Existing health check
+    .route("/webhook/{channel}", post(...))   // Existing webhook
+    .fallback(get(ui_handler))                // Embedded UI assets at /
+```
+
+## Decision 7: Binary Size
+
+**Decision**: Acceptable — well within 25MB constitution target
+
+**Rationale**:
+- Server binary overhead from rust-embed: minimal (embeds pre-built WASM assets)
+- WASM bundle (browser-side): ~3 MB debug, smaller with wasm-opt
+- Current release binary: ~21 MB (LTO + strip)
+- With embedded UI: estimated ~22-23 MB server binary (WASM assets included)
+- The 25MB constitution target applies to the server binary including embedded assets
+
+**Optimization levers if needed**:
+- `trunk build --release` with wasm-opt
+- Explicit `[build] target` in Cargo.toml to prevent WASM opt-level from bleeding into server profile
+
+## Decision 8: Hidden Password Input
+
+**Decision**: `rpassword` crate (already in Cargo.toml)
+
+**Rationale**:
+- Already added as a dependency in the uncommitted onboarding code
+- `rpassword::prompt_password()` handles cross-platform hidden input
+- Lightweight (~3 dependencies), well-maintained
+- No terminal UI framework needed (no `dialoguer`, no `inquire`)
diff --git a/specs/002-onboard-chat-ui/spec.md b/specs/002-onboard-chat-ui/spec.md
new file mode 100644
index 0000000..ee53403
--- /dev/null
+++ b/specs/002-onboard-chat-ui/spec.md
@@ -0,0 +1,115 @@
+# Feature Specification: Onboarding & Built-in Chat UI
+
+**Feature Branch**: `002-onboard-chat-ui`
+**Created**: 2026-02-08
+**Status**: Draft
+**Input**: Secure API key onboarding CLI and built-in web chat interface — two UX essentials missing from the core runtime spec
+
+## Clarifications
+
+### Session 2026-02-08
+
+- Q: Should the chat UI be inline HTML/JS or a Rust/WASM frontend framework? → A: Leptos (Rust/WASM, fine-grained reactivity, axum-native integration via leptos_axum). Renders markdown in LLM responses.
+- Q: Should onboarding verify the API key works via a test API call? → A: No — non-empty validation only (Option A). Fast, offline, no network dependency. Bad keys surface on first message.
+- Q: What happens when user sends a message while AI is still streaming? → A: Block input — disable send while streaming, re-enable when response finishes (Option B).
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - First-Time Onboarding with Secure API Key Entry (Priority: P1)
+
+A new user has just installed exoclaw and wants to start chatting with an AI agent. They run `exoclaw onboard`, choose their LLM provider (Anthropic or OpenAI), and enter their API key. The key is never shown on screen during entry. The system stores the key in a dedicated credential file with restricted file permissions, separate from the main config file. The config file itself never contains the API key — the runtime resolves it at startup from either the credential file or an environment variable.
+
+This is the very first thing a user does after install. It must feel simple, safe, and obvious. A user who completes onboarding should be one command away from a working agent.
+
+**Why this priority**: Without onboarding, a user has to manually create config files and figure out where to put their API key. The core runtime spec (001) assumed env vars, but most users expect a guided setup. This is the front door to the product.
+
+**Independent Test**: Run `exoclaw onboard`, enter a provider and API key, verify the credential file exists with correct permissions, verify the config file is written without the key, then run `exoclaw gateway` and confirm it resolves the key from the credential file.
+
+**Acceptance Scenarios**:
+
+1. **Given** a fresh install with no config file, **When** the user runs `exoclaw onboard`, **Then** the system prompts for provider (defaulting to Anthropic) and API key, writes `~/.exoclaw/config.toml` and `~/.exoclaw/credentials/{provider}.key`, and prints next-step instructions.
+2. **Given** onboarding is complete, **When** the user runs `exoclaw gateway`, **Then** the gateway resolves the API key from the credential file without the user setting any environment variable.
+3. **Given** a user running onboarding, **When** they type their API key, **Then** the characters are not echoed to the terminal (hidden input).
+4. **Given** a completed onboarding, **When** the user inspects `~/.exoclaw/config.toml`, **Then** the file contains provider and model settings but no API key value.
+5. **Given** the credential file exists at `~/.exoclaw/credentials/anthropic.key`, **When** the file permissions are checked, **Then** the file is readable only by the owner (mode 0600) and the parent directory is mode 0700.
+6. **Given** an existing config from a previous onboarding, **When** the user runs `exoclaw onboard` again, **Then** the system overwrites the credential file and updates the config, preserving any non-onboarding settings (plugins, bindings, budgets).
+7. **Given** `ANTHROPIC_API_KEY` is set in the environment, **When** the gateway starts, **Then** the environment variable takes precedence over the credential file.
+8. **Given** a user enters an empty or whitespace-only API key, **When** onboarding validates the input, **Then** the system rejects it with a clear error and does not write any files.
+
+---
+
+### User Story 2 - Built-in Web Chat Interface (Priority: P1)
+
+After starting the gateway, the user opens their browser to the gateway's address (e.g., `http://localhost:7200`) and sees a chat interface built with Leptos — a Rust/WASM frontend framework with fine-grained reactivity. They type a message, press Enter, and see the AI response stream in token-by-token with rendered markdown (code blocks, bold, lists, headers). No npm, no JS build tools. The frontend is a Leptos crate compiled to WASM and served by the same axum gateway, built entirely with Rust tooling (`cargo-leptos`).
+
+This is the simplest possible way to verify the system works and have a conversation. It replaces the need for `websocat` or hand-crafted JSON-RPC messages. A user who completes onboarding and starts the gateway can immediately chat through their browser.
+
+**Why this priority**: The core runtime spec (001) defined everything as WebSocket + JSON-RPC, which requires a developer tool to even test. No normal user will hand-write `{"jsonrpc":"2.0","method":"chat.send","params":{"content":"hello"}}`. The built-in chat UI makes SC-006 from 001-core-runtime ("install to first message in under 10 minutes") actually achievable.
+
+**Independent Test**: Start the gateway, open a browser to the gateway URL, type "hello" in the message box, press Enter, verify the response streams in character-by-character with markdown rendering, verify the conversation persists across messages in the same session.
+
+**Acceptance Scenarios**:
+
+1. **Given** a running gateway on localhost:7200, **When** the user navigates to `http://localhost:7200` in a browser, **Then** the system serves the Leptos chat application (HTML shell + WASM bundle), with no external CDN dependencies.
+2. **Given** the chat page is loaded, **When** the user types a message and presses Enter (or clicks Send), **Then** the page communicates with the gateway via WebSocket using the existing JSON-RPC protocol (`chat.send`) and displays the streamed response tokens as they arrive.
+3. **Given** the gateway requires an auth token (non-loopback bind), **When** the chat page loads, **Then** it prompts the user for the token before connecting and sends it as the first WebSocket message.
+4. **Given** the gateway is in loopback mode (no auth), **When** the chat page loads, **Then** it connects immediately without prompting for a token.
+5. **Given** an active conversation in the chat UI, **When** the user sends a follow-up message, **Then** the response reflects conversation context (the agent remembers prior messages in the session).
+6. **Given** the LLM is streaming a response, **When** tokens arrive, **Then** each token is appended to the response area immediately via Leptos fine-grained reactivity (not buffered until complete), and the view auto-scrolls to show the latest text.
+7. **Given** an LLM response containing markdown (code blocks, bold, lists), **When** rendered in the chat UI, **Then** the markdown is displayed with proper formatting (syntax-highlighted code blocks, styled bold/italic, indented lists).
+8. **Given** the LLM provider is unreachable or returns an error, **When** the user sends a message, **Then** the chat UI displays the error clearly in the conversation thread (not a silent failure or browser console error).
+9. **Given** the LLM is streaming a response, **When** the user attempts to type or send a new message, **Then** the input is disabled until the current response completes, indicating the agent is still responding.
+10. **Given** the gateway is not running, **When** the user navigates to the URL, **Then** the browser shows its standard connection-refused behavior (no special handling needed).
+
+---
+
+### Edge Cases
+
+- What happens when the user runs `exoclaw onboard` but the home directory is read-only or the disk is full? The system reports a clear filesystem error ("cannot write to ~/.exoclaw: permission denied") and does not leave partial files.
+- What happens when the credential file exists but is empty or corrupted? The runtime treats it as missing and falls back to the environment variable. If neither is available, the gateway reports "no API key configured" at startup.
+- What happens when two browser tabs open the chat UI simultaneously? Each tab gets its own WebSocket connection and session. Messages in one tab do not appear in the other.
+- What happens when the user refreshes the chat page? The conversation history from the current session is lost in the UI (it's a stateless page), but the server-side session retains context so the agent still remembers prior messages.
+- What happens when the WebSocket connection drops mid-stream (network blip, laptop sleep)? The chat UI shows a "connection lost" indicator and offers a reconnect action. The server-side session remains intact.
+- What happens when a provider name other than "anthropic" or "openai" is entered during onboarding? The system rejects it with "invalid provider: expected anthropic or openai" and re-prompts.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+**Onboarding**
+
+- **FR-001**: System MUST provide a CLI command (`exoclaw onboard`) that guides first-time setup: provider selection and API key entry.
+- **FR-002**: System MUST accept API key input via hidden terminal entry (characters not echoed to screen).
+- **FR-003**: System MUST store the API key in a dedicated credential file (`~/.exoclaw/credentials/{provider}.key`), separate from the main config file.
+- **FR-004**: Credential files MUST be created with owner-only read/write permissions (mode 0600); the credentials directory MUST be owner-only (mode 0700).
+- **FR-005**: The main config file (`~/.exoclaw/config.toml`) MUST NOT contain API key values. Keys are resolved at runtime.
+- **FR-006**: System MUST resolve API keys in priority order: environment variable first, then credential file, then absent.
+- **FR-007**: System MUST validate that the entered API key is non-empty before writing any files.
+- **FR-008**: Re-running `exoclaw onboard` MUST update credentials and provider/model settings while preserving unrelated config sections (plugins, bindings, budgets, memory).
+
+**Web Chat UI**
+
+- **FR-009**: The gateway MUST serve a Leptos-based chat application at its root URL (`/`), compiled from Rust to WASM with fine-grained reactivity. No external CDN dependencies.
+- **FR-010**: The chat page MUST establish a WebSocket connection to the gateway and communicate using the existing JSON-RPC protocol (`chat.send`).
+- **FR-011**: The chat page MUST display streamed LLM response tokens as they arrive, appending each token immediately via Leptos fine-grained DOM updates (not buffering until completion).
+- **FR-012**: The chat page MUST handle authentication: prompt for a token when the gateway requires one, skip the prompt in loopback mode.
+- **FR-013**: The chat page MUST display errors from the gateway (provider unreachable, budget exceeded, no API key configured) as visible messages in the conversation thread.
+- **FR-014**: The chat page MUST be built entirely with Rust tooling (`cargo-leptos`). No npm, no JS package managers, no JavaScript build steps.
+- **FR-015**: The chat page MUST render markdown in LLM responses: code blocks with syntax highlighting, bold/italic text, lists, and headers.
+- **FR-016**: The chat page MUST disable message input while an LLM response is streaming and re-enable it when the response completes or errors.
+
+### Key Entities
+
+- **Credential File**: A plaintext file containing a single API key for one provider. Located at `~/.exoclaw/credentials/{provider}.key`. Restricted to owner-only permissions. Read at gateway startup as a fallback when the corresponding environment variable is not set.
+- **Chat Session (UI)**: A browser-side conversation state managed by Leptos reactive signals. Tied to a single WebSocket connection. Lost on page refresh, but the server-side session (from 001-core-runtime) retains context for the agent.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: A new user can go from `cargo install exoclaw` to sending their first AI message through the browser chat UI in under 5 minutes, following only: `exoclaw onboard` then `exoclaw gateway` then open browser.
+- **SC-002**: The onboarding flow completes in under 30 seconds for a user who has their API key ready.
+- **SC-003**: The chat page loads in under 500ms including WASM initialization (Leptos hydration).
+- **SC-004**: Streamed tokens appear in the chat UI within 50ms of the gateway receiving them from the LLM provider (fine-grained reactivity overhead).
+- **SC-005**: Credential files are never readable by other users on the system (verified by file permission check).
+- **SC-006**: The chat page works in all modern browsers (Chrome, Firefox, Safari, Edge) that support WebAssembly.
diff --git a/specs/002-onboard-chat-ui/tasks.md b/specs/002-onboard-chat-ui/tasks.md
new file mode 100644
index 0000000..987b989
--- /dev/null
+++ b/specs/002-onboard-chat-ui/tasks.md
@@ -0,0 +1,231 @@
+# Tasks: Onboarding & Built-in Chat UI
+
+**Input**: Design documents from `/specs/002-onboard-chat-ui/`
+**Prerequisites**: plan.md, spec.md, research.md, data-model.md, contracts/routes.md
+
+**Tests**: Included where they validate critical behavior (credential security, config preservation). Browser UI testing is manual.
+
+**Organization**: Tasks are grouped by user story (US1, US2) to enable independent implementation and testing.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g., US1, US2)
+- All paths are relative to repository root
+
+---
+
+## Phase 1: Setup
+
+**Purpose**: Convert project to Cargo workspace and install Leptos build tooling
+
+- [x] T001 Convert `Cargo.toml` to a Cargo workspace — add `[workspace]` section with members `[".","ui"]`. Keep existing `[package]`, `[dependencies]`, etc. intact. Verify `cargo check` still passes after conversion.
+- [x] T002 Create `ui/` crate — `ui/Cargo.toml` with `name = "exoclaw-ui"`, `crate-type = ["cdylib", "rlib"]`, edition 2024. Dependencies: `leptos`, `leptos_meta`, `leptos_router`, `gloo-net`, `pulldown-cmark`, `serde`, `serde_json`. Create `ui/src/lib.rs` with a placeholder `pub fn app() {}`.
+- [x] T003 [P] Add `[package.metadata.leptos]` section to root `Cargo.toml` — (adapted: using trunk+rust-embed instead of cargo-leptos for simpler CSR build).
+- [x] T004 [P] Add `rust-embed`, `mime_guess`, `tower-http[fs]` dependencies to root `Cargo.toml` — (adapted: embedded static assets instead of leptos_axum SSR).
+- [x] T005 Verify `trunk build` succeeds — installed `trunk`, added `wasm32-unknown-unknown` target. Build produces `ui/dist/` with WASM bundle + JS glue + index.html.
+
+**Checkpoint**: `cargo leptos build` succeeds. `cargo check` and `cargo test` still pass for the server crate. The `ui/` crate compiles to WASM.
+
+---
+
+## Phase 2: Foundational
+
+**Purpose**: Commit the existing uncommitted onboarding code and wire Leptos serving into the gateway
+
+**CRITICAL**: These must be complete before US1 tests or US2 components can be verified.
+
+- [x] T006 Commit existing uncommitted onboarding code — (deferred to Phase 5 as a single commit with all changes).
+- [x] T007 Integrate UI serving into `src/gateway/server.rs` — embedded `ui/dist/` via `rust-embed`, added fallback route serving index.html + static assets. Custom routes registered first. Added no-API-key startup warning (T013).
+- [x] T008 [P] Create root Leptos app component in `ui/src/app.rs` — `#[component] pub fn App()` with placeholder text. Mounted via `wasm_bindgen(start)` in `lib.rs`.
+- [x] T009 Verify end-to-end — `cargo check` passes for both crates. `trunk build` produces WASM bundle. 14 existing tests pass.
+
+**Checkpoint**: Gateway serves the Leptos app at `/` and the WebSocket at `/ws` simultaneously. Existing tests pass.
+
+---
+
+## Phase 3: User Story 1 — First-Time Onboarding (Priority: P1)
+
+**Goal**: `exoclaw onboard` guides first-time setup with secure API key storage. Most code already exists in uncommitted changes — this phase adds tests and handles edge cases.
+
+**Independent Test**: Run `exoclaw onboard`, enter provider + key, verify credential file (0600), verify config file has no key, run `exoclaw gateway` and confirm key resolves.
+
+### Tests for User Story 1
+
+- [x] T010 [P] [US1] Write onboarding integration test in `tests/onboard_test.rs` — 5 tests: credential file creation, 0600 permissions, 0700 dir permissions, config without api_key, OpenAI roundtrip.
+- [x] T011 [P] [US1] Write credential resolution tests in `tests/onboard_test.rs` — 6 tests: env var precedence, credential file fallback, empty/whitespace credential files treated as missing, invalid provider rejected by write and config save, empty key rejected.
+
+### Implementation for User Story 1
+
+- [x] T012 [US1] Verify re-onboard preserves unrelated config — test `re_onboard_preserves_unrelated_sections` verifies all sections (gateway, plugins, bindings, budgets, memory) survive re-onboard.
+- [x] T013 [US1] Add "no API key configured" startup warning in `src/gateway/server.rs` — `tracing::warn!` at gateway startup when `config.agent.api_key` is None.
+- [x] T014 [P] [US1] Update `README.md` with onboarding instructions — quickstart includes `cargo run -- onboard`, credential file location, env var precedence documented.
+
+**Checkpoint**: `cargo test` passes including new onboard tests. `exoclaw onboard` → `exoclaw gateway` works end-to-end with key resolved from credential file.
+
+---
+
+## Phase 4: User Story 2 — Built-in Web Chat Interface (Priority: P1)
+
+**Goal**: A Leptos-based chat UI at `/` that connects via WebSocket to the gateway, sends messages via JSON-RPC, and streams responses with markdown rendering. Input disabled while streaming.
+
+**Independent Test**: Start gateway, open `http://localhost:7200`, type "hello", see streamed response with markdown formatting.
+
+**Depends on**: Phase 2 (Leptos serving wired), 001-core-runtime `chat.send` (currently stubbed — UI can be built against stub, full testing requires wired agent loop)
+
+### Implementation for User Story 2
+
+**WebSocket client + JSON-RPC protocol (browser-side)**
+
+- [x] T015 [US2] Create WebSocket client module in `ui/src/ws.rs` — use `gloo-net::websocket::futures::WebSocket` to connect to `/ws`. Functions: `connect(url, token: Option<String>)` → opens WebSocket, sends auth token as first message if provided. `send_chat(ws, content: String)` → sends JSON-RPC `{"jsonrpc":"2.0","id":1,"method":"chat.send","params":{"content":"..."}}`. `StreamEvent` enum matching gateway protocol: `Text(String)`, `ToolUse{name,input}`, `ToolResult(String)`, `Usage{input_tokens,output_tokens}`, `Done`, `Error(String)`. Parse incoming WebSocket messages into `StreamEvent`.
+- [x] T016 [US2] Create reactive chat state in `ui/src/state.rs` — Leptos signals: `messages: RwSignal<Vec<ChatMessage>>`, `input_text: RwSignal<String>`, `is_streaming: RwSignal<bool>`, `is_connected: RwSignal<bool>`, `needs_auth: RwSignal<bool>`, `auth_token: RwSignal<Option<String>>`. `ChatMessage` struct: `role: MessageRole` (User/Assistant/Error), `content: String`, `is_complete: bool`. Functions: `add_user_message()`, `start_assistant_message()`, `append_token(text)`, `complete_message()`, `add_error(msg)`.
+
+**Leptos components**
+
+- [x] T017 [US2] Implement chat container component in `ui/src/components/chat.rs` — `#[component] fn Chat()` renders the full chat layout: message list at top (scrollable), input area at bottom (fixed). Uses signals from `state.rs`. On mount, attempt WebSocket connection (trigger auth prompt if needed). Message list maps over `messages` signal, rendering a `<Message>` component for each.
+- [x] T018 [P] [US2] Implement message bubble component in `ui/src/components/message.rs` — `#[component] fn Message(msg: ChatMessage)` renders a single message. User messages: plain text, right-aligned or distinct style. Assistant messages: rendered as markdown via `pulldown-cmark` → HTML, left-aligned. Error messages: red/warning style. Use `inner_html` for the markdown-rendered output. Streaming messages (is_complete=false) show a blinking cursor indicator.
+- [x] T019 [P] [US2] Implement markdown rendering in `ui/src/markdown.rs` — function `render_markdown(input: &str) -> String` using `pulldown-cmark::Parser` → `pulldown_cmark::html::push_html()`. Add basic CSS classes for code blocks (`<pre><code>`), inline code, bold, italic, lists, headers. Code blocks get a `language-{lang}` class for future syntax highlighting.
+- [x] T020 [P] [US2] Implement message input component in `ui/src/components/input.rs` — `#[component] fn MessageInput()` renders a `<textarea>` bound to `input_text` signal + a Send button. Enter key sends (Shift+Enter for newline). When `is_streaming` is true: disable the textarea and button, show "Agent is responding..." placeholder. On send: call `add_user_message()`, set `is_streaming = true`, call `send_chat()`, spawn async task to read stream events and call `append_token()`/`complete_message()`/`add_error()`, set `is_streaming = false` on Done/Error.
+- [x] T021 [P] [US2] Implement auth prompt component in `ui/src/components/auth_prompt.rs` — `#[component] fn AuthPrompt()` renders a modal/overlay with a text input for the auth token and a Connect button. Shown when `needs_auth` is true. On submit: store token in `auth_token` signal, set `needs_auth = false`, trigger WebSocket connection with the token.
+- [x] T022 [P] [US2] Implement connection status component in `ui/src/components/status.rs` — `#[component] fn ConnectionStatus()` renders a small indicator (dot or text) showing WebSocket connection state. Green/connected when `is_connected` true. Red/"Disconnected — click to reconnect" when false. On click when disconnected: re-attempt WebSocket connection.
+
+**Integration + styling**
+
+- [x] T023 [US2] Wire all components together in `ui/src/app.rs` — replace placeholder with: `<Chat/>` as the main view, `<AuthPrompt/>` conditionally rendered when `needs_auth`, `<ConnectionStatus/>` in a fixed position. Initialize state signals in a `provide_context`. Auto-scroll the message list to bottom on new messages using a Leptos `create_effect` watching `messages` length.
+- [x] T024 [US2] Add CSS styling to the chat UI — inline styles or a `<style>` block in the Leptos app component. Dark theme with light text (matches developer tool aesthetics). Message bubbles with distinct user/assistant/error colors. Fixed input area at bottom. Scrollable message area. Responsive layout (works on mobile widths too). Code blocks with monospace font and subtle background. Keep it minimal — no animations, no transitions, no gradients.
+- [x] T025 [US2] Implement auto-scroll behavior in `ui/src/components/chat.rs` — when new tokens arrive during streaming, auto-scroll the message container to the bottom. Use `web_sys::Element::scroll_into_view()` or set `scrollTop = scrollHeight` on the container. Only auto-scroll if the user hasn't manually scrolled up (respect scroll position).
+- [x] T026 [US2] Add `ui/src/components/mod.rs` — re-export all component modules: `chat`, `message`, `input`, `auth_prompt`, `status`.
+
+**Checkpoint**: `cargo leptos build` succeeds. Gateway serves chat UI at `/`. User can type messages, see them in the chat. WebSocket connects to `/ws`. Streamed responses display token-by-token with markdown rendering. Input disabled while streaming. Auth prompt shown for non-loopback binds. Connection status visible.
+
+---
+
+## Phase 5: Polish & Cross-Cutting Concerns
+
+**Purpose**: Documentation, build verification, end-to-end validation
+
+- [x] T027 [P] Update `CLAUDE.md` with Leptos build instructions — add `cargo leptos build` and `cargo leptos watch` to the Build & Run section. Document the `ui/` crate and workspace structure. Note that `cargo check`/`cargo test`/`cargo clippy` still work for server-only development.
+- [x] T028 [P] Update `examples/config.toml` with onboarding reference — add comment under `[agent]` section: `# Run 'exoclaw onboard' for guided setup, or set key via env var`.
+- [x] T029 Verify release binary size — `cargo leptos build --release`, check `target/release/exoclaw` is under 25MB (constitution V). Check `target/site/pkg/` WASM bundle size. If over budget: enable `wasm-opt -Oz`, verify `[build] target` is set to prevent WASM opt-level bleeding into server binary.
+- [x] T030 Run quickstart validation — follow `specs/002-onboard-chat-ui/quickstart.md` on a clean checkout: build, onboard, start gateway, open browser, send message. Verify the 3-command flow works.
+- [x] T031 Run `cargo clippy` and `cargo fmt --check` for both workspace members — fix any new warnings. Dead-code warnings acceptable during scaffold phase.
+
+**Checkpoint**: All tests pass. Build produces binary under 25MB. Quickstart flow works end-to-end. No clippy warnings (except dead-code).
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+```text
+Phase 1 (Setup) ─────────► Phase 2 (Foundational) ─────┐
+                                                         │
+                                    ┌────────────────────▼─────────────────────┐
+                                    │              Phase 2 complete             │
+                                    └──────┬───────────────────┬───────────────┘
+                                           │                   │
+                               ┌───────────▼───┐   ┌──────────▼──────────┐
+                               │ Phase 3: US1  │   │   Phase 4: US2      │
+                               │ Onboarding    │   │   Chat UI           │
+                               │ (tests+polish)│   │   (Leptos frontend) │
+                               └───────────────┘   └─────────────────────┘
+                                           │                   │
+                                    ┌──────▼───────────────────▼───────────┐
+                                    │     Phase 5: Polish & Validation     │
+                                    └─────────────────────────────────────┘
+```
+
+### User Story Dependencies
+
+- **US1 (Onboarding)**: Depends on Phase 2 (commit baseline). Independent of US2. Most code already exists.
+- **US2 (Chat UI)**: Depends on Phase 2 (Leptos serving wired). Independent of US1. Full end-to-end testing requires 001-core-runtime `chat.send` wired, but UI can be built and visually tested against the stub.
+
+### Within Each User Story
+
+- Tests written first (US1)
+- Data structures before components (US2: state.rs → components)
+- Core components before integration (US2: individual components → app.rs wiring)
+- Integration before styling (US2: wiring → CSS)
+
+### Parallel Opportunities
+
+**Phase 1**: T003 and T004 can run in parallel (different files).
+
+**Phase 3 (US1)**: T010 and T011 (tests) in parallel. T014 (README) parallel with T012/T013.
+
+**Phase 4 (US2)**: After T015 (WebSocket) and T016 (state), all component tasks are parallel:
+```
+T015 (ws.rs) ──┐
+T016 (state.rs)┤
+               ├──► T017 (chat.rs)
+               ├──► T018 [P] (message.rs)
+               ├──► T019 [P] (markdown.rs)
+               ├──► T020 [P] (input.rs)
+               ├──► T021 [P] (auth_prompt.rs)
+               └──► T022 [P] (status.rs)
+                        │
+                        ▼
+               T023 (app.rs wiring)
+               T024 (CSS)
+               T025 (auto-scroll)
+               T026 (mod.rs)
+```
+
+**US1 and US2 can run in parallel** since they modify different files entirely.
+
+---
+
+## Implementation Strategy
+
+### MVP First (US1 Only)
+
+1. Complete Phase 1: Setup (T001-T005)
+2. Complete Phase 2: Foundational (T006-T009)
+3. Complete Phase 3: US1 Onboarding (T010-T014)
+4. **STOP and VALIDATE**: `exoclaw onboard` → `exoclaw gateway` works. Key resolved from credential file.
+5. This gives users a secure, guided setup flow.
+
+### Full Delivery
+
+1. Setup + Foundational → Workspace builds, Leptos serves placeholder
+2. **US1** → Onboarding works → **Secure setup flow**
+3. **US2** → Chat UI works → **Browser-based chat with streaming + markdown**
+4. Polish → Binary size verified, quickstart validated, docs updated
+
+### Parallel Strategy
+
+With two agents/developers:
+- **Agent A**: US1 (Phase 3) — small scope, mostly tests + polish on existing code
+- **Agent B**: US2 (Phase 4) — larger scope, all new Leptos frontend code
+- Both start after Phase 2 completes
+- Merge into Phase 5 together
+
+---
+
+## Summary
+
+| Phase | Story | Tasks | Parallel Tasks |
+|-------|-------|-------|----------------|
+| 1. Setup | — | T001-T005 (5) | T003, T004 |
+| 2. Foundational | — | T006-T009 (4) | T008 |
+| 3. US1 Onboarding | P1 | T010-T014 (5) | T010, T011, T014 |
+| 4. US2 Chat UI | P1 | T015-T026 (12) | T018, T019, T020, T021, T022 |
+| 5. Polish | — | T027-T031 (5) | T027, T028 |
+| **Total** | | **31 tasks** | **12 parallelizable** |
+
+**Suggested MVP scope**: Phase 1 + Phase 2 + Phase 3 (US1) = **14 tasks** to secure onboarding.
+
+**Full scope**: All 31 tasks for onboarding + browser chat UI.
+
+---
+
+## Notes
+
+- [P] tasks = different files, no dependencies on incomplete tasks
+- [Story] label maps each task to its user story for traceability
+- US1 and US2 are independently completable and testable
+- US2's full end-to-end test (actual LLM response) requires 001-core-runtime `chat.send` to be wired — until then, the UI works against the gateway stub (which returns `{"queued": true}`)
+- Commit after each task or logical group
+- Stop at any checkpoint to validate the story independently
+- The echo plugin (`examples/echo-plugin/`) is unaffected by workspace conversion
diff --git a/src/config.rs b/src/config.rs
index 5c9417a..2de5713 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -1,9 +1,10 @@
-use serde::Deserialize;
-use std::path::PathBuf;
+use crate::fs_util::{home_dir, set_secure_dir_permissions, set_secure_file_permissions};
+use serde::{Deserialize, Serialize};
+use std::path::{Path, PathBuf};
 use tracing::info;
 
 /// Top-level configuration loaded from TOML.
-#[derive(Debug, Default, Deserialize)]
+#[derive(Debug, Default, Deserialize, Serialize)]
 #[serde(default)]
 pub struct ExoclawConfig {
     pub gateway: GatewayConfig,
@@ -18,7 +19,7 @@ pub struct ExoclawConfig {
     pub memory: MemoryConfig,
 }
 
-#[derive(Debug, Deserialize)]
+#[derive(Debug, Deserialize, Serialize)]
 pub struct GatewayConfig {
     #[serde(default = "default_port")]
     pub port: u16,
@@ -42,7 +43,7 @@ fn default_bind() -> String {
     "127.0.0.1".into()
 }
 
-#[derive(Debug, Clone, Deserialize)]
+#[derive(Debug, Clone, Deserialize, Serialize)]
 pub struct AgentDefConfig {
     #[serde(default = "default_agent_id")]
     pub id: String,
@@ -89,7 +90,7 @@ fn default_max_tokens() -> u32 {
     4096
 }
 
-#[derive(Debug, Clone, Deserialize)]
+#[derive(Debug, Clone, Deserialize, Serialize)]
 pub struct PluginConfig {
     pub name: String,
     pub path: String,
@@ -97,7 +98,7 @@ pub struct PluginConfig {
     pub capabilities: Vec<String>,
 }
 
-#[derive(Debug, Clone, Deserialize)]
+#[derive(Debug, Clone, Deserialize, Serialize)]
 pub struct BindingConfig {
     pub agent_id: String,
     pub channel: Option<String>,
@@ -107,14 +108,14 @@ pub struct BindingConfig {
     pub team_id: Option<String>,
 }
 
-#[derive(Debug, Default, Clone, Deserialize)]
+#[derive(Debug, Default, Clone, Deserialize, Serialize)]
 pub struct BudgetConfig {
     pub session: Option<u64>,
     pub daily: Option<u64>,
     pub monthly: Option<u64>,
 }
 
-#[derive(Debug, Clone, Deserialize)]
+#[derive(Debug, Clone, Deserialize, Serialize)]
 pub struct MemoryConfig {
     #[serde(default = "default_episodic_window")]
     pub episodic_window: u32,
@@ -145,7 +146,7 @@ fn default_semantic_enabled() -> bool {
 /// 2. `~/.exoclaw/config.toml`
 /// 3. Zero-config defaults (no file needed)
 pub fn load() -> anyhow::Result<ExoclawConfig> {
-    let path = config_path();
+    let path = resolve_path();
 
     if path.exists() {
         let content = std::fs::read_to_string(&path)
@@ -166,20 +167,50 @@ pub fn load() -> anyhow::Result<ExoclawConfig> {
     }
 }
 
-fn config_path() -> PathBuf {
+/// Resolve config file path based on EXOCLAW_CONFIG or ~/.exoclaw/config.toml.
+pub fn resolve_path() -> PathBuf {
     if let Ok(path) = std::env::var("EXOCLAW_CONFIG") {
         return PathBuf::from(path);
     }
-    let home = std::env::var("HOME").unwrap_or_else(|_| ".".into());
-    PathBuf::from(home).join(".exoclaw").join("config.toml")
+    let home = home_dir().unwrap_or_else(|_| PathBuf::from("."));
+    home.join(".exoclaw").join("config.toml")
+}
+
+/// Save config to the default path with secure permissions.
+pub fn save(config: &ExoclawConfig) -> anyhow::Result<PathBuf> {
+    let path = resolve_path();
+    save_to_path(config, &path)?;
+    Ok(path)
+}
+
+/// Save config to an explicit path (used by onboarding and tests).
+pub fn save_to_path(config: &ExoclawConfig, path: &Path) -> anyhow::Result<()> {
+    validate(config)?;
+    let content =
+        toml::to_string_pretty(config).map_err(|e| anyhow::anyhow!("toml encode: {e}"))?;
+
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent)
+            .map_err(|e| anyhow::anyhow!("failed to create {}: {e}", parent.display()))?;
+        set_secure_dir_permissions(parent)?;
+    }
+
+    std::fs::write(path, content)
+        .map_err(|e| anyhow::anyhow!("failed to write {}: {e}", path.display()))?;
+    set_secure_file_permissions(path)?;
+    Ok(())
 }
 
 /// Resolve API key from environment variables if not set in config.
 fn resolve_api_key(config: &mut ExoclawConfig) {
     if config.agent.api_key.is_none() {
         config.agent.api_key = match config.agent.provider.as_str() {
-            "anthropic" => std::env::var("ANTHROPIC_API_KEY").ok(),
-            "openai" => std::env::var("OPENAI_API_KEY").ok(),
+            "anthropic" => std::env::var("ANTHROPIC_API_KEY")
+                .ok()
+                .or_else(|| crate::secrets::load_api_key("anthropic")),
+            "openai" => std::env::var("OPENAI_API_KEY")
+                .ok()
+                .or_else(|| crate::secrets::load_api_key("openai")),
             _ => None,
         };
     }
diff --git a/src/fs_util.rs b/src/fs_util.rs
new file mode 100644
index 0000000..bbaf473
--- /dev/null
+++ b/src/fs_util.rs
@@ -0,0 +1,32 @@
+use std::path::Path;
+
+/// Resolve the user's home directory, or error if unset.
+pub fn home_dir() -> anyhow::Result<std::path::PathBuf> {
+    std::env::var("HOME")
+        .map(std::path::PathBuf::from)
+        .map_err(|_| anyhow::anyhow!("HOME environment variable is not set"))
+}
+
+#[cfg(unix)]
+pub fn set_secure_dir_permissions(path: &Path) -> anyhow::Result<()> {
+    use std::os::unix::fs::PermissionsExt;
+    std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o700))
+        .map_err(|e| anyhow::anyhow!("failed to chmod 700 {}: {e}", path.display()))
+}
+
+#[cfg(not(unix))]
+pub fn set_secure_dir_permissions(_path: &Path) -> anyhow::Result<()> {
+    Ok(())
+}
+
+#[cfg(unix)]
+pub fn set_secure_file_permissions(path: &Path) -> anyhow::Result<()> {
+    use std::os::unix::fs::PermissionsExt;
+    std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o600))
+        .map_err(|e| anyhow::anyhow!("failed to chmod 600 {}: {e}", path.display()))
+}
+
+#[cfg(not(unix))]
+pub fn set_secure_file_permissions(_path: &Path) -> anyhow::Result<()> {
+    Ok(())
+}
diff --git a/src/gateway/server.rs b/src/gateway/server.rs
index 5855b30..7f3e759 100644
--- a/src/gateway/server.rs
+++ b/src/gateway/server.rs
@@ -8,11 +8,16 @@ use axum::{
     routing::{get, post},
 };
 use futures::SinkExt;
+use rust_embed::Embed;
 use std::collections::HashMap;
 use std::sync::Arc;
 use tokio::sync::{Mutex, RwLock};
 use tracing::{info, warn};
 
+#[derive(Embed)]
+#[folder = "ui/dist/"]
+struct UiAssets;
+
 use super::auth;
 use super::protocol::RpcResult;
 use crate::agent::AgentEvent;
@@ -105,6 +110,12 @@ pub async fn run(config: ExoclawConfig, token: Option<String>) -> anyhow::Result
         }
     }
 
+    if config.agent.api_key.is_none() {
+        warn!(
+            "no API key configured — run 'exoclaw onboard' or set ANTHROPIC_API_KEY/OPENAI_API_KEY"
+        );
+    }
+
     let addr = format!("{}:{}", config.gateway.bind, config.gateway.port);
 
     let state = Arc::new(AppState {
@@ -121,6 +132,7 @@ pub async fn run(config: ExoclawConfig, token: Option<String>) -> anyhow::Result
         .route("/ws", get(ws_handler))
         .route("/health", get(health))
         .route("/webhook/{channel}", post(webhook_handler))
+        .fallback(get(ui_handler))
         .with_state(state);
 
     let listener = tokio::net::TcpListener::bind(&addr).await?;
@@ -140,6 +152,36 @@ async fn health() -> &'static str {
     "ok"
 }
 
+async fn ui_handler(uri: axum::http::Uri) -> impl IntoResponse {
+    let path = uri.path().trim_start_matches('/');
+    // Serve index.html for root path or unknown paths (SPA routing)
+    let path = if path.is_empty() { "index.html" } else { path };
+
+    match UiAssets::get(path) {
+        Some(file) => {
+            let mime = mime_guess::from_path(path).first_or_octet_stream();
+            (
+                StatusCode::OK,
+                [(axum::http::header::CONTENT_TYPE, mime.as_ref())],
+                file.data.to_vec(),
+            )
+                .into_response()
+        }
+        None => {
+            // SPA fallback: serve index.html for unmatched paths
+            match UiAssets::get("index.html") {
+                Some(file) => (
+                    StatusCode::OK,
+                    [(axum::http::header::CONTENT_TYPE, "text/html")],
+                    file.data.to_vec(),
+                )
+                    .into_response(),
+                None => (StatusCode::NOT_FOUND, "UI not available").into_response(),
+            }
+        }
+    }
+}
+
 async fn ws_handler(ws: WebSocketUpgrade, State(state): State<Arc<AppState>>) -> impl IntoResponse {
     ws.on_upgrade(move |socket| handle_connection(socket, state))
 }
diff --git a/src/lib.rs b/src/lib.rs
index d1c0325..bc25000 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,9 +1,11 @@
 pub mod agent;
 pub mod bus;
 pub mod config;
+pub mod fs_util;
 pub mod gateway;
 pub mod memory;
 pub mod router;
 pub mod sandbox;
+pub mod secrets;
 pub mod store;
 pub mod types;
diff --git a/src/main.rs b/src/main.rs
index 2cedaa7..6c5185c 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -1,4 +1,5 @@
 use clap::{Parser, Subcommand};
+use std::io::{self, Write};
 use tracing::info;
 use tracing_subscriber::EnvFilter;
 
@@ -13,6 +14,13 @@ struct Cli {
 
 #[derive(Subcommand)]
 enum Commands {
+    /// Run first-time onboarding and save config with an API key
+    Onboard {
+        /// Provider to configure (anthropic|openai). If omitted, prompts interactively.
+        #[arg(long)]
+        provider: Option<String>,
+    },
+
     /// Start the gateway server
     Gateway {
         /// Port to bind to (overrides config file)
@@ -58,6 +66,7 @@ async fn main() -> anyhow::Result<()> {
     let cli = Cli::parse();
 
     match cli.command {
+        Commands::Onboard { provider } => run_onboard(provider),
         Commands::Gateway { port, bind, token } => {
             let mut config = exoclaw::config::load()?;
 
@@ -93,3 +102,88 @@ async fn main() -> anyhow::Result<()> {
         }
     }
 }
+
+fn run_onboard(provider_arg: Option<String>) -> anyhow::Result<()> {
+    let mut config = exoclaw::config::load()?;
+
+    println!("exoclaw onboarding");
+    println!(
+        "This writes config to {}.",
+        exoclaw::config::resolve_path().display()
+    );
+
+    let provider = resolve_provider(provider_arg, &config.agent.provider)?;
+    let provider_default_model = default_model_for_provider(&provider);
+    let provider_label = provider_display_name(&provider);
+    let key_label = format!("{provider_label} API key");
+
+    let key = rpassword::prompt_password(format!("{key_label}: "))?;
+    let key = key.trim().to_string();
+    if key.is_empty() {
+        anyhow::bail!("{key_label} cannot be empty");
+    }
+    let key_path = exoclaw::secrets::store_api_key(&provider, &key)?;
+
+    config.agent.provider = provider.clone();
+    config.agent.model = provider_default_model.to_string();
+    // Keep config key-free; runtime resolves key from env or credential file.
+    config.agent.api_key = None;
+
+    let path = exoclaw::config::save(&config)?;
+    println!("Saved config to {}", path.display());
+    println!("Saved API key to {}", key_path.display());
+    println!(
+        "Configured provider={} model={}",
+        config.agent.provider, config.agent.model
+    );
+    println!("Next: cargo run -- gateway");
+
+    Ok(())
+}
+
+fn resolve_provider(input: Option<String>, current: &str) -> anyhow::Result<String> {
+    let provider = match input {
+        Some(value) => value,
+        None => {
+            let default = if current == "openai" || current == "anthropic" {
+                current
+            } else {
+                "anthropic"
+            };
+            prompt_with_default("Provider (anthropic/openai)", default)?
+        }
+    };
+
+    let normalized = provider.trim().to_ascii_lowercase();
+    if normalized != "anthropic" && normalized != "openai" {
+        anyhow::bail!("invalid provider '{provider}': expected anthropic or openai");
+    }
+    Ok(normalized)
+}
+
+fn prompt_with_default(prompt: &str, default: &str) -> anyhow::Result<String> {
+    print!("{prompt} [{default}]: ");
+    io::stdout().flush()?;
+    let mut input = String::new();
+    io::stdin().read_line(&mut input)?;
+    let input = input.trim();
+    if input.is_empty() {
+        Ok(default.to_string())
+    } else {
+        Ok(input.to_string())
+    }
+}
+
+fn provider_display_name(provider: &str) -> &'static str {
+    match provider {
+        "openai" => "OpenAI",
+        _ => "Anthropic",
+    }
+}
+
+fn default_model_for_provider(provider: &str) -> &'static str {
+    match provider {
+        "openai" => "gpt-4o",
+        _ => "claude-sonnet-4-5-20250929",
+    }
+}
diff --git a/src/secrets.rs b/src/secrets.rs
new file mode 100644
index 0000000..59d37c2
--- /dev/null
+++ b/src/secrets.rs
@@ -0,0 +1,108 @@
+use crate::fs_util::{home_dir, set_secure_dir_permissions, set_secure_file_permissions};
+use std::path::{Path, PathBuf};
+
+fn default_state_dir() -> PathBuf {
+    home_dir()
+        .unwrap_or_else(|_| PathBuf::from("."))
+        .join(".exoclaw")
+}
+
+fn state_dir() -> PathBuf {
+    if let Ok(path) = std::env::var("EXOCLAW_CONFIG") {
+        let config_path = PathBuf::from(path);
+        if let Some(parent) = config_path.parent() {
+            return parent.to_path_buf();
+        }
+    }
+    default_state_dir()
+}
+
+fn credentials_dir_for(state_dir: &Path) -> PathBuf {
+    state_dir.join("credentials")
+}
+
+fn normalize_provider(provider: &str) -> anyhow::Result<String> {
+    let provider = provider.trim().to_ascii_lowercase();
+    match provider.as_str() {
+        "anthropic" | "openai" => Ok(provider),
+        _ => anyhow::bail!("unsupported provider for key store: {provider}"),
+    }
+}
+
+fn key_file_path_for(state_dir: &Path, provider: &str) -> anyhow::Result<PathBuf> {
+    let provider = normalize_provider(provider)?;
+    Ok(credentials_dir_for(state_dir).join(format!("{provider}.key")))
+}
+
+pub fn write_key_to(state_dir: &Path, provider: &str, api_key: &str) -> anyhow::Result<PathBuf> {
+    let api_key = api_key.trim();
+    if api_key.is_empty() {
+        anyhow::bail!("API key cannot be empty");
+    }
+
+    let dir = credentials_dir_for(state_dir);
+    std::fs::create_dir_all(&dir)
+        .map_err(|e| anyhow::anyhow!("failed to create {}: {e}", dir.display()))?;
+    set_secure_dir_permissions(&dir)?;
+
+    let path = key_file_path_for(state_dir, provider)?;
+    std::fs::write(&path, api_key)
+        .map_err(|e| anyhow::anyhow!("failed to write {}: {e}", path.display()))?;
+    set_secure_file_permissions(&path)?;
+    Ok(path)
+}
+
+pub fn read_key_from(state_dir: &Path, provider: &str) -> Option<String> {
+    let path = key_file_path_for(state_dir, provider).ok()?;
+    let value = std::fs::read_to_string(path).ok()?;
+    let value = value.trim();
+    if value.is_empty() {
+        None
+    } else {
+        Some(value.to_string())
+    }
+}
+
+/// Store a provider API key in ~/.exoclaw/credentials/{provider}.key.
+pub fn store_api_key(provider: &str, api_key: &str) -> anyhow::Result<PathBuf> {
+    write_key_to(&state_dir(), provider, api_key)
+}
+
+/// Load a provider API key from ~/.exoclaw/credentials/{provider}.key.
+pub fn load_api_key(provider: &str) -> Option<String> {
+    read_key_from(&state_dir(), provider)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{read_key_from, write_key_to};
+    use std::path::PathBuf;
+
+    fn tmp_dir() -> PathBuf {
+        let nanos = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .expect("system clock before epoch")
+            .as_nanos();
+        let path = std::env::temp_dir().join(format!("exoclaw-secrets-test-{nanos}"));
+        std::fs::create_dir_all(&path).expect("create temp dir");
+        path
+    }
+
+    #[test]
+    fn writes_and_reads_provider_key() {
+        let dir = tmp_dir();
+        let path = write_key_to(&dir, "anthropic", "sk-ant-test").expect("write key");
+        assert!(path.exists());
+        let loaded = read_key_from(&dir, "anthropic");
+        assert_eq!(loaded.as_deref(), Some("sk-ant-test"));
+        std::fs::remove_dir_all(dir).ok();
+    }
+
+    #[test]
+    fn rejects_unknown_provider() {
+        let dir = tmp_dir();
+        let err = write_key_to(&dir, "bad/../../provider", "x").expect_err("should fail");
+        assert!(err.to_string().contains("unsupported provider"));
+        std::fs::remove_dir_all(dir).ok();
+    }
+}
diff --git a/tests/onboard_test.rs b/tests/onboard_test.rs
new file mode 100644
index 0000000..21e42a9
--- /dev/null
+++ b/tests/onboard_test.rs
@@ -0,0 +1,312 @@
+use exoclaw::config::{ExoclawConfig, save_to_path};
+use exoclaw::secrets::{read_key_from, write_key_to};
+use std::path::PathBuf;
+
+fn tmp_dir(label: &str) -> PathBuf {
+    let nanos = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .expect("system clock before epoch")
+        .as_nanos();
+    let path = std::env::temp_dir().join(format!("exoclaw-onboard-{label}-{nanos}"));
+    std::fs::create_dir_all(&path).expect("create temp dir");
+    path
+}
+
+// ---------------------------------------------------------------------------
+// T010: Fresh onboard creates credential file with correct permissions
+// ---------------------------------------------------------------------------
+
+#[test]
+fn write_key_creates_credential_file() {
+    let dir = tmp_dir("write-key");
+    let path = write_key_to(&dir, "anthropic", "sk-ant-test-123").expect("write key");
+
+    assert!(path.exists(), "credential file should exist");
+    let contents = std::fs::read_to_string(&path).unwrap();
+    assert_eq!(contents, "sk-ant-test-123");
+
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+#[cfg(unix)]
+#[test]
+fn credential_file_has_0600_permissions() {
+    use std::os::unix::fs::PermissionsExt;
+
+    let dir = tmp_dir("perms-file");
+    let path = write_key_to(&dir, "anthropic", "sk-test").expect("write key");
+
+    let mode = std::fs::metadata(&path).unwrap().permissions().mode() & 0o777;
+    assert_eq!(
+        mode, 0o600,
+        "credential file should be mode 0600, got {mode:04o}"
+    );
+
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+#[cfg(unix)]
+#[test]
+fn credentials_dir_has_0700_permissions() {
+    use std::os::unix::fs::PermissionsExt;
+
+    let dir = tmp_dir("perms-dir");
+    write_key_to(&dir, "anthropic", "sk-test").expect("write key");
+
+    let cred_dir = dir.join("credentials");
+    let mode = std::fs::metadata(&cred_dir).unwrap().permissions().mode() & 0o777;
+    assert_eq!(
+        mode, 0o700,
+        "credentials dir should be mode 0700, got {mode:04o}"
+    );
+
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+#[test]
+fn save_config_without_api_key_field() {
+    let dir = tmp_dir("no-api-key");
+    let config_path = dir.join("config.toml");
+
+    let mut config = ExoclawConfig::default();
+    config.agent.provider = "anthropic".into();
+    config.agent.model = "claude-sonnet-4-5-20250929".into();
+    config.agent.api_key = None;
+
+    save_to_path(&config, &config_path).expect("save config");
+
+    let content = std::fs::read_to_string(&config_path).unwrap();
+    // The TOML should not contain an api_key field (None is omitted by serde)
+    assert!(
+        !content.contains("api_key"),
+        "config file should not contain api_key field, got:\n{content}"
+    );
+
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+// ---------------------------------------------------------------------------
+// T012: Re-onboard preserves unrelated config sections
+// ---------------------------------------------------------------------------
+
+#[test]
+fn re_onboard_preserves_unrelated_sections() {
+    let dir = tmp_dir("re-onboard");
+    let config_path = dir.join("config.toml");
+
+    // Write an initial config with plugins, bindings, budgets, memory, gateway
+    let initial_toml = r#"
+[gateway]
+port = 9999
+bind = "0.0.0.0"
+
+[agent]
+provider = "anthropic"
+model = "claude-sonnet-4-5-20250929"
+max_tokens = 4096
+
+[[plugins]]
+name = "echo"
+path = "/opt/plugins/echo.wasm"
+capabilities = ["http:api.example.com"]
+
+[[bindings]]
+agent_id = "my-agent"
+channel = "telegram"
+
+[budgets]
+session = 50000
+daily = 500000
+monthly = 5000000
+
+[memory]
+episodic_window = 10
+semantic_enabled = false
+"#;
+    std::fs::write(&config_path, initial_toml).unwrap();
+
+    // Load the config (simulating what run_onboard does)
+    let mut config: ExoclawConfig = toml::from_str(initial_toml).unwrap();
+
+    // Simulate onboard: only change provider and model, clear api_key
+    config.agent.provider = "openai".into();
+    config.agent.model = "gpt-4o".into();
+    config.agent.api_key = None;
+
+    save_to_path(&config, &config_path).expect("save updated config");
+
+    // Re-load and verify unrelated sections are preserved
+    let reloaded: ExoclawConfig =
+        toml::from_str(&std::fs::read_to_string(&config_path).unwrap()).unwrap();
+
+    // Agent section updated
+    assert_eq!(reloaded.agent.provider, "openai");
+    assert_eq!(reloaded.agent.model, "gpt-4o");
+    assert!(reloaded.agent.api_key.is_none());
+
+    // Gateway preserved
+    assert_eq!(reloaded.gateway.port, 9999);
+    assert_eq!(reloaded.gateway.bind, "0.0.0.0");
+
+    // Plugins preserved
+    assert_eq!(reloaded.plugins.len(), 1);
+    assert_eq!(reloaded.plugins[0].name, "echo");
+    assert_eq!(reloaded.plugins[0].path, "/opt/plugins/echo.wasm");
+    assert_eq!(
+        reloaded.plugins[0].capabilities,
+        vec!["http:api.example.com"]
+    );
+
+    // Bindings preserved
+    assert_eq!(reloaded.bindings.len(), 1);
+    assert_eq!(reloaded.bindings[0].agent_id, "my-agent");
+    assert_eq!(reloaded.bindings[0].channel.as_deref(), Some("telegram"));
+
+    // Budgets preserved
+    assert_eq!(reloaded.budgets.session, Some(50000));
+    assert_eq!(reloaded.budgets.daily, Some(500000));
+    assert_eq!(reloaded.budgets.monthly, Some(5000000));
+
+    // Memory preserved
+    assert_eq!(reloaded.memory.episodic_window, 10);
+    assert!(!reloaded.memory.semantic_enabled);
+
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+// ---------------------------------------------------------------------------
+// T011: Credential resolution tests
+// ---------------------------------------------------------------------------
+
+#[test]
+fn env_var_takes_precedence_over_credential_file() {
+    let dir = tmp_dir("env-precedence");
+    let config_path = dir.join("config.toml");
+
+    // Write a credential file
+    write_key_to(&dir, "anthropic", "sk-from-file").expect("write key");
+
+    // Write config pointing to this dir
+    let config_toml = "[agent]\nprovider = \"anthropic\"\n";
+    std::fs::write(&config_path, config_toml).unwrap();
+
+    // Set env vars: EXOCLAW_CONFIG points to our temp config, and set API key env var
+    // SAFETY: env var manipulation for testing
+    unsafe {
+        std::env::set_var("EXOCLAW_CONFIG", config_path.to_str().unwrap());
+        std::env::set_var("ANTHROPIC_API_KEY", "sk-from-env");
+    }
+
+    let config = exoclaw::config::load().expect("load config");
+
+    unsafe {
+        std::env::remove_var("EXOCLAW_CONFIG");
+        std::env::remove_var("ANTHROPIC_API_KEY");
+    }
+
+    // Env var should win
+    assert_eq!(config.agent.api_key.as_deref(), Some("sk-from-env"));
+
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+#[test]
+fn credential_file_used_when_env_var_absent() {
+    // Test read_key_from directly to avoid env var race conditions in parallel tests.
+    // The full config::load() -> resolve_api_key() -> load_api_key() chain delegates
+    // to read_key_from internally; testing it directly proves the fallback works.
+    let dir = tmp_dir("cred-file-fallback");
+
+    write_key_to(&dir, "openai", "sk-from-cred-file").expect("write key");
+
+    let loaded = read_key_from(&dir, "openai");
+    assert_eq!(loaded.as_deref(), Some("sk-from-cred-file"));
+
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+#[test]
+fn empty_credential_file_treated_as_missing() {
+    let dir = tmp_dir("empty-cred");
+
+    // Write an empty credential file
+    let cred_dir = dir.join("credentials");
+    std::fs::create_dir_all(&cred_dir).unwrap();
+    std::fs::write(cred_dir.join("anthropic.key"), "").unwrap();
+
+    let result = read_key_from(&dir, "anthropic");
+    assert!(result.is_none(), "empty credential file should return None");
+
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+#[test]
+fn whitespace_only_credential_file_treated_as_missing() {
+    let dir = tmp_dir("ws-cred");
+
+    let cred_dir = dir.join("credentials");
+    std::fs::create_dir_all(&cred_dir).unwrap();
+    std::fs::write(cred_dir.join("anthropic.key"), "   \n  ").unwrap();
+
+    let result = read_key_from(&dir, "anthropic");
+    assert!(
+        result.is_none(),
+        "whitespace-only credential file should return None"
+    );
+
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+#[test]
+fn invalid_provider_rejected_by_write() {
+    let dir = tmp_dir("bad-provider");
+    let err = write_key_to(&dir, "deepmind", "sk-test").expect_err("should reject");
+    assert!(
+        err.to_string().contains("unsupported provider"),
+        "error should mention unsupported provider: {err}"
+    );
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+#[test]
+fn invalid_provider_rejected_by_config_save() {
+    let dir = tmp_dir("bad-provider-cfg");
+    let config_path = dir.join("config.toml");
+
+    let mut config = ExoclawConfig::default();
+    config.agent.provider = "deepmind".into();
+
+    let err = save_to_path(&config, &config_path).expect_err("should reject invalid provider");
+    assert!(
+        err.to_string().contains("invalid provider"),
+        "error should mention invalid provider: {err}"
+    );
+
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+#[test]
+fn empty_api_key_rejected_by_write() {
+    let dir = tmp_dir("empty-key");
+    let err = write_key_to(&dir, "anthropic", "").expect_err("should reject empty key");
+    assert!(
+        err.to_string().contains("cannot be empty"),
+        "error should mention empty: {err}"
+    );
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+#[test]
+fn read_key_roundtrip_openai() {
+    let dir = tmp_dir("openai-rt");
+
+    write_key_to(&dir, "openai", "sk-openai-test-key").expect("write key");
+    let loaded = read_key_from(&dir, "openai");
+    assert_eq!(loaded.as_deref(), Some("sk-openai-test-key"));
+
+    // Anthropic key should not exist
+    let other = read_key_from(&dir, "anthropic");
+    assert!(other.is_none());
+
+    std::fs::remove_dir_all(&dir).ok();
+}
diff --git a/ui/Cargo.toml b/ui/Cargo.toml
new file mode 100644
index 0000000..b339e69
--- /dev/null
+++ b/ui/Cargo.toml
@@ -0,0 +1,33 @@
+[package]
+name = "exoclaw-ui"
+version = "0.1.0"
+edition = "2024"
+description = "Leptos chat UI for exoclaw gateway"
+
+[lib]
+crate-type = ["cdylib", "rlib"]
+
+[dependencies]
+leptos = { version = "0.7", features = ["csr"] }
+leptos_router = { version = "0.7" }
+leptos_meta = { version = "0.7" }
+gloo-net = { version = "0.6", features = ["websocket"] }
+pulldown-cmark = "0.12"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+wasm-bindgen = "0.2"
+wasm-bindgen-futures = "0.4"
+web-sys = { version = "0.3", features = [
+    "HtmlElement",
+    "HtmlTextAreaElement",
+    "HtmlInputElement",
+    "Element",
+    "ScrollIntoViewOptions",
+    "ScrollBehavior",
+    "KeyboardEvent",
+    "Window",
+    "Location",
+] }
+js-sys = "0.3"
+futures = "0.3"
+log = "0.4"
diff --git a/ui/Trunk.toml b/ui/Trunk.toml
new file mode 100644
index 0000000..47497de
--- /dev/null
+++ b/ui/Trunk.toml
@@ -0,0 +1,2 @@
+[build]
+dist = "dist"
diff --git a/ui/index.html b/ui/index.html
new file mode 100644
index 0000000..e65f194
--- /dev/null
+++ b/ui/index.html
@@ -0,0 +1,10 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8"/>
+    <meta name="viewport" content="width=device-width, initial-scale=1"/>
+    <title>exoclaw</title>
+    <link data-trunk rel="rust"/>
+</head>
+<body></body>
+</html>
diff --git a/ui/src/app.rs b/ui/src/app.rs
new file mode 100644
index 0000000..b6cb63c
--- /dev/null
+++ b/ui/src/app.rs
@@ -0,0 +1,334 @@
+use crate::components::auth_prompt::AuthPrompt;
+use crate::components::chat::Chat;
+use crate::components::input::MessageInput;
+use crate::components::status::ConnectionStatus;
+use crate::state::ChatState;
+use leptos::prelude::*;
+
+#[component]
+pub fn App() -> impl IntoView {
+    let state = ChatState::new();
+    provide_context(state);
+
+    // Attempt initial WebSocket connection
+    wasm_bindgen_futures::spawn_local(async move {
+        match crate::ws::connect(None).await {
+            Ok(_) => {
+                state.is_connected.set(true);
+            }
+            Err(e) => {
+                if e.contains("auth") {
+                    state.needs_auth.set(true);
+                }
+            }
+        }
+    });
+
+    view! {
+        <style>{STYLES}</style>
+        <main class="app">
+            <header class="app-header">
+                <h1>"exoclaw"</h1>
+                <ConnectionStatus/>
+            </header>
+            <Chat/>
+            <MessageInput/>
+            {move || {
+                if state.needs_auth.get() {
+                    view! { <AuthPrompt/> }.into_any()
+                } else {
+                    view! {}.into_any()
+                }
+            }}
+        </main>
+    }
+}
+
+const STYLES: &str = r#"
+    * {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+    }
+
+    body {
+        background: #1a1a2e;
+        color: #e0e0e0;
+        font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+        height: 100vh;
+        overflow: hidden;
+    }
+
+    .app {
+        display: flex;
+        flex-direction: column;
+        height: 100vh;
+        max-width: 900px;
+        margin: 0 auto;
+    }
+
+    .app-header {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        padding: 12px 16px;
+        border-bottom: 1px solid #2a2a4a;
+    }
+
+    .app-header h1 {
+        font-size: 1.1rem;
+        font-weight: 600;
+        color: #8888cc;
+    }
+
+    .chat-container {
+        flex: 1;
+        overflow: hidden;
+        display: flex;
+        flex-direction: column;
+    }
+
+    .message-list {
+        flex: 1;
+        overflow-y: auto;
+        padding: 16px;
+        display: flex;
+        flex-direction: column;
+        gap: 12px;
+    }
+
+    .message-list::-webkit-scrollbar {
+        width: 6px;
+    }
+
+    .message-list::-webkit-scrollbar-track {
+        background: transparent;
+    }
+
+    .message-list::-webkit-scrollbar-thumb {
+        background: #3a3a5a;
+        border-radius: 3px;
+    }
+
+    .message {
+        max-width: 80%;
+        padding: 10px 14px;
+        border-radius: 12px;
+        line-height: 1.5;
+        word-wrap: break-word;
+    }
+
+    .message-user {
+        align-self: flex-end;
+        background: #2a4a8a;
+        color: #e0e8ff;
+        border-bottom-right-radius: 4px;
+    }
+
+    .message-assistant {
+        align-self: flex-start;
+        background: #2a2a3e;
+        color: #d0d0e0;
+        border-bottom-left-radius: 4px;
+    }
+
+    .message-error {
+        align-self: center;
+        background: #4a1a1a;
+        color: #ff8888;
+        border-radius: 8px;
+        font-size: 0.9em;
+    }
+
+    .message-content p {
+        margin: 0.4em 0;
+    }
+
+    .message-content p:first-child {
+        margin-top: 0;
+    }
+
+    .message-content p:last-child {
+        margin-bottom: 0;
+    }
+
+    .message-content pre {
+        background: #111122;
+        padding: 10px;
+        border-radius: 6px;
+        overflow-x: auto;
+        margin: 0.5em 0;
+    }
+
+    .message-content code {
+        font-family: "JetBrains Mono", "Fira Code", monospace;
+        font-size: 0.9em;
+    }
+
+    .message-content pre code {
+        background: none;
+        padding: 0;
+    }
+
+    .message-content code {
+        background: #111122;
+        padding: 2px 5px;
+        border-radius: 3px;
+    }
+
+    .streaming-dot {
+        display: inline-block;
+        animation: pulse 1s ease-in-out infinite;
+        color: #8888cc;
+    }
+
+    @keyframes pulse {
+        0%, 100% { opacity: 1; }
+        50% { opacity: 0.3; }
+    }
+
+    .input-area {
+        display: flex;
+        gap: 8px;
+        padding: 12px 16px;
+        border-top: 1px solid #2a2a4a;
+        background: #1a1a2e;
+    }
+
+    .chat-input {
+        flex: 1;
+        background: #222240;
+        color: #e0e0e0;
+        border: 1px solid #3a3a5a;
+        border-radius: 8px;
+        padding: 10px 12px;
+        font-family: inherit;
+        font-size: 0.95rem;
+        resize: none;
+        min-height: 44px;
+        max-height: 160px;
+        outline: none;
+    }
+
+    .chat-input:focus {
+        border-color: #5a5a8a;
+    }
+
+    .chat-input:disabled {
+        opacity: 0.5;
+    }
+
+    .chat-input::placeholder {
+        color: #666688;
+    }
+
+    .send-button {
+        background: #3a5aaa;
+        color: #e0e8ff;
+        border: none;
+        border-radius: 8px;
+        padding: 10px 20px;
+        font-size: 0.95rem;
+        cursor: pointer;
+        align-self: flex-end;
+    }
+
+    .send-button:hover:not(:disabled) {
+        background: #4a6abb;
+    }
+
+    .send-button:disabled {
+        opacity: 0.4;
+        cursor: not-allowed;
+    }
+
+    .connection-status {
+        display: flex;
+        align-items: center;
+        gap: 6px;
+        cursor: pointer;
+        font-size: 0.85rem;
+    }
+
+    .status-dot {
+        width: 8px;
+        height: 8px;
+        border-radius: 50%;
+    }
+
+    .status-dot.connected {
+        background: #44bb66;
+    }
+
+    .status-dot.disconnected {
+        background: #cc4444;
+    }
+
+    .status-label {
+        color: #888;
+    }
+
+    .auth-overlay {
+        position: fixed;
+        top: 0;
+        left: 0;
+        right: 0;
+        bottom: 0;
+        background: rgba(0, 0, 0, 0.7);
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        z-index: 100;
+    }
+
+    .auth-modal {
+        background: #222240;
+        border: 1px solid #3a3a5a;
+        border-radius: 12px;
+        padding: 32px;
+        max-width: 400px;
+        width: 90%;
+    }
+
+    .auth-modal h2 {
+        margin-bottom: 8px;
+        color: #aaaadd;
+    }
+
+    .auth-modal p {
+        margin-bottom: 16px;
+        color: #888;
+        font-size: 0.9rem;
+    }
+
+    .auth-input {
+        width: 100%;
+        background: #1a1a2e;
+        color: #e0e0e0;
+        border: 1px solid #3a3a5a;
+        border-radius: 8px;
+        padding: 10px 12px;
+        font-size: 0.95rem;
+        margin-bottom: 12px;
+        outline: none;
+    }
+
+    .auth-input:focus {
+        border-color: #5a5a8a;
+    }
+
+    .auth-button {
+        width: 100%;
+        background: #3a5aaa;
+        color: #e0e8ff;
+        border: none;
+        border-radius: 8px;
+        padding: 10px;
+        font-size: 0.95rem;
+        cursor: pointer;
+    }
+
+    .auth-button:hover {
+        background: #4a6abb;
+    }
+"#;
diff --git a/ui/src/components/auth_prompt.rs b/ui/src/components/auth_prompt.rs
new file mode 100644
index 0000000..bbcbf62
--- /dev/null
+++ b/ui/src/components/auth_prompt.rs
@@ -0,0 +1,51 @@
+use crate::state::ChatState;
+use leptos::prelude::*;
+
+#[component]
+pub fn AuthPrompt() -> impl IntoView {
+    let state = use_context::<ChatState>().expect("ChatState in context");
+    let token_input = RwSignal::new(String::new());
+
+    let on_submit = move |_| {
+        let tok = token_input.get();
+        let tok = tok.trim().to_string();
+        if !tok.is_empty() {
+            state.auth_token.set(Some(tok));
+            state.needs_auth.set(false);
+        }
+    };
+
+    let on_keydown = move |ev: web_sys::KeyboardEvent| {
+        if ev.key() == "Enter" {
+            ev.prevent_default();
+            let tok = token_input.get();
+            let tok = tok.trim().to_string();
+            if !tok.is_empty() {
+                state.auth_token.set(Some(tok));
+                state.needs_auth.set(false);
+            }
+        }
+    };
+
+    view! {
+        <div class="auth-overlay">
+            <div class="auth-modal">
+                <h2>"Authentication Required"</h2>
+                <p>"Enter your gateway token to connect."</p>
+                <input
+                    type="password"
+                    class="auth-input"
+                    placeholder="Token..."
+                    prop:value=move || token_input.get()
+                    on:input:target=move |ev| {
+                        token_input.set(ev.target().value());
+                    }
+                    on:keydown=on_keydown
+                />
+                <button class="auth-button" on:click=on_submit>
+                    "Connect"
+                </button>
+            </div>
+        </div>
+    }
+}
diff --git a/ui/src/components/chat.rs b/ui/src/components/chat.rs
new file mode 100644
index 0000000..788b37c
--- /dev/null
+++ b/ui/src/components/chat.rs
@@ -0,0 +1,44 @@
+use crate::components::message::MessageBubble;
+use crate::state::ChatState;
+use leptos::prelude::*;
+
+#[component]
+pub fn Chat() -> impl IntoView {
+    let state = use_context::<ChatState>().expect("ChatState in context");
+    let container_ref: NodeRef<leptos::html::Div> = NodeRef::new();
+    let user_scrolled_up = RwSignal::new(false);
+
+    // Auto-scroll when messages change
+    Effect::new(move |_| {
+        // Track messages signal to trigger on changes
+        let _msgs = state.messages.get();
+        if user_scrolled_up.get() {
+            return;
+        }
+        if let Some(el) = container_ref.get() {
+            let el: &web_sys::Element = &el;
+            el.set_scroll_top(el.scroll_height());
+        }
+    });
+
+    // Detect if user scrolled up
+    let on_scroll = move |_| {
+        if let Some(el) = container_ref.get() {
+            let el: &web_sys::Element = &el;
+            let at_bottom = el.scroll_height() - el.scroll_top() - el.client_height() < 40;
+            user_scrolled_up.set(!at_bottom);
+        }
+    };
+
+    view! {
+        <div class="chat-container">
+            <div class="message-list" node_ref=container_ref on:scroll=on_scroll>
+                {move || {
+                    state.messages.get().into_iter().map(|msg| {
+                        view! { <MessageBubble msg=msg/> }
+                    }).collect::<Vec<_>>()
+                }}
+            </div>
+        </div>
+    }
+}
diff --git a/ui/src/components/input.rs b/ui/src/components/input.rs
new file mode 100644
index 0000000..8e6f96c
--- /dev/null
+++ b/ui/src/components/input.rs
@@ -0,0 +1,132 @@
+use crate::state::ChatState;
+use crate::ws;
+use leptos::prelude::*;
+
+#[component]
+pub fn MessageInput() -> impl IntoView {
+    let state = use_context::<ChatState>().expect("ChatState in context");
+
+    let on_send = move || {
+        let content = state.input_text.get();
+        let content = content.trim().to_string();
+        if content.is_empty() || state.is_streaming.get() {
+            return;
+        }
+
+        state.add_user_message(content.clone());
+        state.input_text.set(String::new());
+        state.is_streaming.set(true);
+        state.start_assistant_message();
+
+        wasm_bindgen_futures::spawn_local(async move {
+            let token = state.auth_token.get();
+            let conn = ws::connect(token).await;
+            match conn {
+                Ok(mut conn) => {
+                    state.is_connected.set(true);
+                    if let Err(e) = ws::send_chat(&mut conn.write, &content, 1).await {
+                        state.add_error(e);
+                        state.is_streaming.set(false);
+                        state.is_connected.set(false);
+                        return;
+                    }
+
+                    use futures::StreamExt;
+                    use gloo_net::websocket::Message;
+
+                    while let Some(msg) = conn.read.next().await {
+                        match msg {
+                            Ok(Message::Text(text)) => {
+                                if let Some(event) = ws::parse_event(&text) {
+                                    match event {
+                                        ws::StreamEvent::Text(t) => {
+                                            state.append_token(&t);
+                                        }
+                                        ws::StreamEvent::ToolUse { name, input } => {
+                                            state.append_token(&format!(
+                                                "\n[tool: {} input: {}]\n",
+                                                name, input
+                                            ));
+                                        }
+                                        ws::StreamEvent::Done => {
+                                            state.complete_message();
+                                            state.is_streaming.set(false);
+                                            break;
+                                        }
+                                        ws::StreamEvent::Error(e) => {
+                                            state.complete_message();
+                                            state.add_error(e);
+                                            state.is_streaming.set(false);
+                                            break;
+                                        }
+                                    }
+                                }
+                            }
+                            Ok(Message::Bytes(_)) => {}
+                            Err(e) => {
+                                state.complete_message();
+                                state.add_error(format!("WebSocket error: {}", e));
+                                state.is_streaming.set(false);
+                                state.is_connected.set(false);
+                                break;
+                            }
+                        }
+                    }
+                }
+                Err(e) => {
+                    if e.contains("auth") {
+                        state.needs_auth.set(true);
+                    }
+                    state.add_error(e);
+                    state.is_streaming.set(false);
+                    state.is_connected.set(false);
+                }
+            }
+        });
+    };
+
+    let on_send_click = {
+        let on_send = on_send.clone();
+        move |_| on_send()
+    };
+
+    let on_keydown = move |ev: web_sys::KeyboardEvent| {
+        if ev.key() == "Enter" && !ev.shift_key() {
+            ev.prevent_default();
+            on_send();
+        }
+    };
+
+    let is_disabled = move || state.is_streaming.get() || !state.is_connected.get();
+    let placeholder = move || {
+        if state.is_streaming.get() {
+            "Agent is responding..."
+        } else if !state.is_connected.get() {
+            "Disconnected..."
+        } else {
+            "Type a message... (Enter to send, Shift+Enter for newline)"
+        }
+    };
+
+    view! {
+        <div class="input-area">
+            <textarea
+                class="chat-input"
+                prop:value=move || state.input_text.get()
+                prop:disabled=is_disabled
+                placeholder=placeholder
+                on:input:target=move |ev| {
+                    state.input_text.set(ev.target().value());
+                }
+                on:keydown=on_keydown
+            ></textarea>
+            <button
+                class="send-button"
+                prop:disabled=is_disabled
+                on:click=on_send_click
+            >
+                "Send"
+            </button>
+        </div>
+    }
+}
diff --git a/ui/src/components/message.rs b/ui/src/components/message.rs
new file mode 100644
index 0000000..35c3fe9
--- /dev/null
+++ b/ui/src/components/message.rs
@@ -0,0 +1,42 @@
+use crate::markdown;
+use crate::state::{ChatMessage, MessageRole};
+use leptos::prelude::*;
+
+#[component]
+pub fn MessageBubble(msg: ChatMessage) -> impl IntoView {
+    let class = match msg.role {
+        MessageRole::User => "message message-user",
+        MessageRole::Assistant => "message message-assistant",
+        MessageRole::Error => "message message-error",
+    };
+
+    let content_view = match msg.role {
+        MessageRole::Assistant => {
+            let html = markdown::render(&msg.content);
+            view! {
+                <div class="message-content" inner_html=html></div>
+            }
+            .into_any()
+        }
+        _ => {
+            let text = msg.content.clone();
+            view! {
+                <div class="message-content">{text}</div>
+            }
+            .into_any()
+        }
+    };
+
+    let streaming_indicator = if !msg.is_complete {
+        view! { <span class="streaming-dot">"..."</span> }.into_any()
+    } else {
+        view! {}.into_any()
+    };
+
+    view! {
+        <div class=class>
+            {content_view}
+            {streaming_indicator}
+        </div>
+    }
+}
diff --git a/ui/src/components/mod.rs b/ui/src/components/mod.rs
new file mode 100644
index 0000000..e69d499
--- /dev/null
+++ b/ui/src/components/mod.rs
@@ -0,0 +1,5 @@
+pub mod auth_prompt;
+pub mod chat;
+pub mod input;
+pub mod message;
+pub mod status;
diff --git a/ui/src/components/status.rs b/ui/src/components/status.rs
new file mode 100644
index 0000000..2107e28
--- /dev/null
+++ b/ui/src/components/status.rs
@@ -0,0 +1,50 @@
+use crate::state::ChatState;
+use leptos::prelude::*;
+
+#[component]
+pub fn ConnectionStatus() -> impl IntoView {
+    let state = use_context::<ChatState>().expect("ChatState in context");
+
+    let dot_class = move || {
+        if state.is_connected.get() {
+            "status-dot connected"
+        } else {
+            "status-dot disconnected"
+        }
+    };
+
+    let label = move || {
+        if state.is_connected.get() {
+            "Connected"
+        } else {
+            "Disconnected"
+        }
+    };
+
+    let on_click = move |_| {
+        if !state.is_connected.get() {
+            // Trigger reconnect by spawning connection attempt
+            let token = state.auth_token.get();
+            wasm_bindgen_futures::spawn_local(async move {
+                match crate::ws::connect(token).await {
+                    Ok(_) => {
+                        state.is_connected.set(true);
+                    }
+                    Err(e) => {
+                        if e.contains("auth") {
+                            state.needs_auth.set(true);
+                        }
+                        state.add_error(format!("Reconnect failed: {}", e));
+                    }
+                }
+            });
+        }
+    };
+
+    view! {
+        <div class="connection-status" on:click=on_click title=label>
+            <span class=dot_class></span>
+            <span class="status-label">{label}</span>
+        </div>
+    }
+}
diff --git a/ui/src/lib.rs b/ui/src/lib.rs
new file mode 100644
index 0000000..aa58eab
--- /dev/null
+++ b/ui/src/lib.rs
@@ -0,0 +1,14 @@
+pub mod app;
+pub mod components;
+pub mod markdown;
+pub mod state;
+pub mod ws;
+
+pub use app::App;
+
+use wasm_bindgen::prelude::*;
+
+#[wasm_bindgen(start)]
+pub fn main() {
+    leptos::mount::mount_to_body(App);
+}
diff --git a/ui/src/markdown.rs b/ui/src/markdown.rs
new file mode 100644
index 0000000..69b16a5
--- /dev/null
+++ b/ui/src/markdown.rs
@@ -0,0 +1,14 @@
+use pulldown_cmark::{Event, Parser, html};
+
+pub fn render(input: &str) -> String {
+    // Convert raw HTML events to escaped text to prevent XSS.
+    // pulldown-cmark passes through raw HTML by default; converting
+    // Html/InlineHtml to Text causes push_html to escape them.
+    let parser = Parser::new(input).map(|event| match event {
+        Event::Html(html) | Event::InlineHtml(html) => Event::Text(html),
+        other => other,
+    });
+    let mut html_output = String::new();
+    html::push_html(&mut html_output, parser);
+    html_output
+}
diff --git a/ui/src/state.rs b/ui/src/state.rs
new file mode 100644
index 0000000..a01ff17
--- /dev/null
+++ b/ui/src/state.rs
@@ -0,0 +1,88 @@
+use leptos::prelude::*;
+
+#[derive(Clone, Debug, PartialEq)]
+pub enum MessageRole {
+    User,
+    Assistant,
+    Error,
+}
+
+#[derive(Clone, Debug)]
+pub struct ChatMessage {
+    pub role: MessageRole,
+    pub content: String,
+    pub is_complete: bool,
+}
+
+#[derive(Clone, Copy)]
+pub struct ChatState {
+    pub messages: RwSignal<Vec<ChatMessage>>,
+    pub input_text: RwSignal<String>,
+    pub is_streaming: RwSignal<bool>,
+    pub is_connected: RwSignal<bool>,
+    pub needs_auth: RwSignal<bool>,
+    pub auth_token: RwSignal<Option<String>>,
+}
+
+impl ChatState {
+    pub fn new() -> Self {
+        Self {
+            messages: RwSignal::new(Vec::new()),
+            input_text: RwSignal::new(String::new()),
+            is_streaming: RwSignal::new(false),
+            is_connected: RwSignal::new(false),
+            needs_auth: RwSignal::new(false),
+            auth_token: RwSignal::new(None),
+        }
+    }
+
+    pub fn add_user_message(&self, content: String) {
+        self.messages.update(|msgs| {
+            msgs.push(ChatMessage {
+                role: MessageRole::User,
+                content,
+                is_complete: true,
+            });
+        });
+    }
+
+    pub fn start_assistant_message(&self) {
+        self.messages.update(|msgs| {
+            msgs.push(ChatMessage {
+                role: MessageRole::Assistant,
+                content: String::new(),
+                is_complete: false,
+            });
+        });
+    }
+
+    pub fn append_token(&self, text: &str) {
+        self.messages.update(|msgs| {
+            if let Some(last) = msgs.last_mut() {
+                if last.role == MessageRole::Assistant && !last.is_complete {
+                    last.content.push_str(text);
+                }
+            }
+        });
+    }
+
+    pub fn complete_message(&self) {
+        self.messages.update(|msgs| {
+            if let Some(last) = msgs.last_mut() {
+                if last.role == MessageRole::Assistant {
+                    last.is_complete = true;
+                }
+            }
+        });
+    }
+
+    pub fn add_error(&self, msg: String) {
+        self.messages.update(|msgs| {
+            msgs.push(ChatMessage {
+                role: MessageRole::Error,
+                content: msg,
+                is_complete: true,
+            });
+        });
+    }
+}
diff --git a/ui/src/ws.rs b/ui/src/ws.rs
new file mode 100644
index 0000000..c0e204d
--- /dev/null
+++ b/ui/src/ws.rs
@@ -0,0 +1,104 @@
+use futures::{SinkExt, StreamExt};
+use gloo_net::websocket::{Message, futures::WebSocket};
+use serde_json::{Value, json};
+
+#[derive(Debug, Clone)]
+pub enum StreamEvent {
+    Text(String),
+    ToolUse { name: String, input: String },
+    Done,
+    Error(String),
+}
+
+fn ws_url() -> Result<String, String> {
+    let window = web_sys::window().ok_or("no window")?;
+    let location = window.location();
+    let protocol = location.protocol().map_err(|_| "no protocol")?;
+    let host = location.host().map_err(|_| "no host")?;
+    let ws_protocol = if protocol == "https:" { "wss:" } else { "ws:" };
+    Ok(format!("{}//{}/ws", ws_protocol, host))
+}
+
+pub fn parse_event(msg: &str) -> Option<StreamEvent> {
+    let v: Value = serde_json::from_str(msg).ok()?;
+    let event = v.get("event")?.as_str()?;
+    match event {
+        "text" => {
+            let data = v.get("data")?.as_str()?;
+            Some(StreamEvent::Text(data.to_string()))
+        }
+        "tool_use" => {
+            let data = v.get("data")?;
+            let name = data.get("name")?.as_str()?.to_string();
+            let input = data.get("input").map(|v| v.to_string()).unwrap_or_default();
+            Some(StreamEvent::ToolUse { name, input })
+        }
+        "done" => Some(StreamEvent::Done),
+        "error" => {
+            let data = v
+                .get("data")
+                .and_then(|d| d.as_str())
+                .unwrap_or("unknown error");
+            Some(StreamEvent::Error(data.to_string()))
+        }
+        _ => None,
+    }
+}
+
+pub struct WsConnection {
+    pub write: futures::stream::SplitSink<WebSocket, Message>,
+    pub read: futures::stream::SplitStream<WebSocket>,
+}
+
+pub async fn connect(token: Option<String>) -> Result<WsConnection, String> {
+    let url = ws_url()?;
+    let ws = WebSocket::open(&url).map_err(|e| format!("WebSocket open failed: {}", e))?;
+    let (mut write, mut read) = ws.split();
+
+    if let Some(tok) = token {
+        let auth_msg = json!({"token": tok}).to_string();
+        write
+            .send(Message::Text(auth_msg))
+            .await
+            .map_err(|e| format!("send auth failed: {}", e))?;
+
+        // Wait for auth response
+        let resp = read
+            .next()
+            .await
+            .ok_or("connection closed during auth")?
+            .map_err(|e| format!("read auth response failed: {}", e))?;
+
+        let resp_text = match resp {
+            Message::Text(t) => t,
+            Message::Bytes(b) => {
+                String::from_utf8(b).map_err(|_| "invalid utf8 in auth response")?
+            }
+        };
+
+        let v: Value =
+            serde_json::from_str(&resp_text).map_err(|_| "invalid JSON in auth response")?;
+        if v.get("ok").and_then(|v| v.as_bool()) != Some(true) {
+            return Err("authentication failed".to_string());
+        }
+    }
+
+    Ok(WsConnection { write, read })
+}
+
+pub async fn send_chat(
+    write: &mut futures::stream::SplitSink<WebSocket, Message>,
+    content: &str,
+    id: u32,
+) -> Result<(), String> {
+    let msg = json!({
+        "jsonrpc": "2.0",
+        "id": id,
+        "method": "chat.send",
+        "params": {"content": content}
+    });
+    write
+        .send(Message::Text(msg.to_string()))
+        .await
+        .map_err(|e| format!("send failed: {}", e))
+}