docs: add web frontend usage

Co-Authored-By: Claude <noreply@anthropic.com>

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
 

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)