1 files changed, 103 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1d6e60c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,103 @@
+# Dispatch Web
+
+The **web frontend** for [Dispatch](../arch-rewrite) — a separate repo built to the same
+methodology (thin shell + pure feature libraries + a backend-driven *surface* host). It consumes
+the backend's typed contracts over HTTP + a WebSocket and ships no business logic the backend
+doesn't expose.
+
+- **Stack:** Bun + Vite + Svelte 5 (runes) + TypeScript (strict). Biome (lint/format), Vitest +
+  `@testing-library/svelte` (tests).
+- **Slice 1 (current):** the **surface system** — connects to the backend's surface WebSocket,
+  fetches the surface *catalog*, and renders any backend-declared *surface* generically (e.g. the
+  live "Loaded Extensions" surface). Chat UI is a later slice.
+
+---
+
+## Prerequisites
+
+- [Bun](https://bun.sh) (v1.3+).
+- **The backend repo as a sibling directory** — this repo links `@dispatch/ui-contract` from
+  `../arch-rewrite` via a `file:` dependency:
+  ```
+  dispatch/
+    arch-rewrite/    # the backend (Dispatch server)
+    dispatch-web/    # this repo
+  ```
+- The **backend server running** for surfaces to appear (see `../arch-rewrite/README.md`).
+
+```sh
+cd dispatch-web
+bun install          # links @dispatch/ui-contract from ../arch-rewrite
+```
+
+---
+
+## Run it (visit locally)
+
+```sh
+# 1) start the backend (sibling repo) — HTTP :24203 + surface WS :24205
+cd ../arch-rewrite && bun run dev
+
+# 2) start this dev server — Vite on :24204
+cd ../dispatch-web && bun run dev
+```
+
+Open **http://localhost:24204**. You'll see the surface catalog (e.g. "Loaded Extensions"); the
+frontend connects to the backend's surface WebSocket at `ws://localhost:24205` (override with
+`VITE_WS_URL`).
+
+> **Tip — run both at once with live reload:** the backend repo ships `../arch-rewrite/bin/up`
+> (also `bun run dev:all` there) which starts the backend (`bun --watch`) + this dev server
+> (Vite HMR) together; **Ctrl-C stops both**.
+
+---
+
+## Visiting over a LAN / Tailscale
+
+The dev server is configured (`vite.config.ts`) to bind **all interfaces** (`server.host: true`)
+and accept **any Host header** (`server.allowedHosts: true`) — so it's reachable from another
+device on your tailnet. This is safe ONLY because you run it on a **private/local network, not
+exposed to the internet** (`allowedHosts: true` disables Vite's DNS-rebinding host check).
+
+When browsing from a **different device than the one running the backend**, set two things:
+
+1. **Reach the dev server:** open `http://<this-machine-tailscale-name>:24204`. (The backend's Bun
+   servers already bind all interfaces, so `:24203`/`:24205` are reachable over Tailscale too.)
+2. **Point the frontend at the backend's WebSocket.** The WS URL runs in *your browser*, so
+   `localhost` would mean *your* device — set it to the backend host. Create `dispatch-web/.env`:
+   ```sh
+   VITE_WS_URL=ws://<backend-machine-tailscale-name>:24205
+   ```
+   Vite auto-loads `.env`; restart `bun run dev` after changing it.
+
+---
+
+## Structure (slice 1)
+
+```
+src/
+  app/                  composition root — owns protocol state (runes), wires the socket, renders
+  core/protocol/        PURE op-protocol reducer (catalog/subscribe/update/invoke) — zero I/O
+  features/surface-host/  the generic surface interpreter + thin field components (toggle/…)
+  adapters/ws/          injected WebSocket client (pure codec + reconnect; socket injected)
+```
+
+The surface vocabulary (`SurfaceSpec`, field kinds, the WS protocol) is the backend's
+`@dispatch/ui-contract`, mirrored in-repo for reference at `.dispatch/ui-contract.reference.md`.
+
+---
+
+## Development
+
+```sh
+bun run dev          # Vite dev server (:24204)
+bun run build        # production build → dist/
+bun run typecheck    # svelte-check
+bun run test         # vitest
+bun run check        # biome (.ts/.js; .svelte correctness is svelte-check's job)
+```
+
+## Documentation
+
+- **Design + plan:** `../arch-rewrite/notes/frontend-design.md`
+- **Build rules:** `AGENTS.md` · **Orchestration:** `ORCHESTRATOR.md` · **Vocabulary:** `GLOSSARY.md`