diff --git a/README.md b/README.md
index 972d766..6314c75 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,7 @@ A runnable Go backend MVP skeleton that manages local workspaces, file operation
 
 ### Not implemented in v1
 
-Docker, authentication, Git integration, LSP, AI Agent orchestration, web frontend, and full watcher/WebSocket event streaming are out of scope for the first version.
+ Docker, authentication, Git integration, LSP, AI Agent orchestration, production web frontend, and full watcher/WebSocket event streaming are out of scope for the first version. An initial frontend scaffold lives in [`web/`](web/README.md).
 
 ## Run
 
diff --git a/web/README.md b/web/README.md
new file mode 100644
index 0000000..c2dd666
--- /dev/null
+++ b/web/README.md
@@ -0,0 +1,36 @@
+# codespace-web
+
+Frontend IDE shell for the codespace Go backend.
+
+## Scope
+
+This package is a runnable **UI scaffold only**. It provides the workspace layout, a mock file explorer, a Monaco editor wrapper, and an xterm terminal wrapper. It does not yet connect to the Go API.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `pnpm install` | Install dependencies |
+| `pnpm dev` | Start the Vite dev server |
+| `pnpm lint` | Run ESLint |
+| `pnpm build` | Type-check and build for production |
+
+## Stack
+
+- Vite + React 19 + TypeScript
+- Tailwind CSS v4
+- react-router v7
+- Zustand for local UI state
+- TanStack Query (provider only; no real API calls yet)
+- `@monaco-editor/react` editor wrapper
+- `@xterm/xterm` + `@xterm/addon-fit` terminal wrapper
+- `react-resizable-panels` for layout splits
+- `lucide-react` for icons
+
+## Non-goals
+
+- Backend API integration (reserved file only at `src/lib/api/client.ts`)
+- Authentication
+- WebSocket terminal or process streaming
+- i18n
+- Tests (no test framework until business logic is added)