diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..c054b1d8
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,95 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a customized offline deployment of **DeerFlow** — a LangGraph-based AI super agent platform. The repo contains two sub-projects:
+
+- `offline-backend-20260512/backend/` — Python backend (FastAPI Gateway + LangGraph agent runtime)
+- `frontend-web/` — Vite + React 19 frontend (TypeScript, pnpm)
+
+Managed together via shell scripts in `scripts/`.
+
+## Commands
+
+### Full Application (from repo root)
+
+```bash
+./scripts/start-all.sh    # Start backend + frontend as background daemons
+./scripts/stop-all.sh     # Stop both
+./scripts/restart-all.sh  # Restart both
+./scripts/status.sh       # Check running status
+```
+
+Logs and PID files are written to `.runtime/logs/` and `.runtime/pids/`.
+
+### Backend Only (from `offline-backend-20260512/backend/`)
+
+```bash
+make install    # Install Python dependencies (uv)
+make dev        # Run Gateway API with hot-reload on port 8001
+make gateway    # Run Gateway API without reload
+make test       # Run all tests: PYTHONPATH=. uv run pytest tests/ -v
+make lint       # Lint with ruff
+make format     # Format with ruff
+```
+
+Run a single test file:
+```bash
+PYTHONPATH=. uv run pytest tests/test_<feature>.py -v
+```
+
+### Frontend Only (from `frontend-web/`)
+
+```bash
+pnpm install    # Install dependencies
+pnpm dev        # Start Vite dev server on port 5174
+pnpm build      # Production build
+pnpm typecheck  # TypeScript type checking (tsc --noEmit)
+```
+
+## Service Ports
+
+| Service | Port | Notes |
+|---------|------|-------|
+| Backend (Gateway API) | 8001 | FastAPI + LangGraph runtime |
+| Frontend (Vite) | 5174 | React SPA |
+
+Frontend connects to backend via env vars `VITE_BACKEND_BASE_URL` and `VITE_LANGGRAPH_BASE_URL` (injected by `scripts/start-frontend.sh`).
+
+## Architecture
+
+### Backend
+
+The backend (`offline-backend-20260512/backend/`) is split into two layers:
+
+- **`packages/harness/deerflow/`** — publishable agent framework (`deerflow.*` imports): LangGraph lead agent, middleware chain, sandbox, tools, MCP, memory, models, skills. **Never imports from `app.*`.**
+- **`app/`** — application layer (`app.*` imports): FastAPI Gateway routers, IM channel integrations (Feishu, Slack, Telegram, DingTalk).
+
+The **Lead Agent** (`deerflow/agents/lead_agent/`) is the single LangGraph graph entry point. It wraps a middleware chain (~18 middlewares assembled in strict order) around LLM calls, handling: thread isolation, sandbox lifecycle, uploads, memory, plan mode, vision, subagent delegation, and loop detection.
+
+**Middleware order matters** — middlewares are appended in a fixed sequence; `ClarificationMiddleware` must always be last. See `offline-backend-20260512/backend/CLAUDE.md` for the full ordered list.
+
+**Harness → App import firewall** is enforced by `tests/test_harness_boundary.py` (runs in CI).
+
+### Frontend
+
+The frontend (`frontend-web/`) is a React 19 + Vite SPA:
+
+- **Routing**: React Router v7; top-level routes in `src/pages/PageRoutes.tsx`, workspace sub-routes in `src/pages/WorkspaceRoutes.tsx`
+- **Pages**: `ChatPage` (thread chat), `AgentChatPage` (custom agent chat), `AgentsPage`/`NewAgentPage` (agent management), `ScheduledTasksPage`/`ScheduledTaskRunDetailPage` (scheduled tasks)
+- **State**: TanStack Query for server state, context providers (`SubtasksProvider`, `ArtifactsProvider`, `PromptInputProvider`) scoped to `WorkspaceRoutes`
+- **LLM streaming**: `@langchain/langgraph-sdk` streams messages from the backend via SSE
+- **UI**: Radix UI primitives + TailwindCSS v4 + shadcn-style components in `src/components/ui/`
+- **Shims**: `src/shims/` provides `next/link` and `next/navigation` polyfills (original code was Next.js)
+
+### Configuration
+
+Backend config lives in `offline-backend-20260512/backend/config.yaml`. Values starting with `$` resolve as environment variables (e.g., `$OPENAI_API_KEY`). MCP servers and skills are configured in `extensions_config.json` in the same directory.
+
+## Detailed Backend Reference
+
+The backend has its own comprehensive documentation at:
+- `offline-backend-20260512/backend/CLAUDE.md` — architecture, middleware chain, all API routes, config schema, sandbox/memory/subagent systems
+- `offline-backend-20260512/backend/README.md` — setup guide, technology stack