diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..6085d77
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,48 @@
+# Zendegi
+
+Turborepo monorepo (pnpm) for a timeline web app. TanStack Start frontend with an embedded Flutter timeline widget.
+
+## Stack
+
+- **apps/web** — TanStack Start (React 19, Vite, Tailwind CSS v4)
+- **packages/auth** — better-auth wrapper
+- **packages/db** — Drizzle ORM + PostgreSQL (Docker)
+- **packages/env** — Type-safe env vars (t3-env + Zod)
+- **packages/config** — Shared TypeScript config
+- **packages/eslint-config** — Shared ESLint config (base + react)
+- **packages/z-timeline** — Flutter web app (embedded in the web page)
+
+## Lint Commands
+
+### Whole stack
+
+```sh
+pnpm check          # turbo lint + check-types + prettier --check
+pnpm fix            # turbo lint --fix + prettier --write
+```
+
+### Individual packages
+
+```sh
+# ESLint
+pnpm --filter web lint             # apps/web
+pnpm --filter @zendegi/auth lint   # packages/auth
+pnpm --filter @zendegi/db lint     # packages/db
+pnpm --filter @zendegi/env lint    # packages/env
+
+# Type checking
+pnpm --filter web check-types
+pnpm --filter @zendegi/auth check-types
+pnpm --filter @zendegi/db check-types
+pnpm --filter @zendegi/env check-types
+
+# Flutter (packages/z-timeline)
+cd packages/z-timeline && dart analyze
+```
+
+### Prettier (root-level)
+
+```sh
+prettier --check .     # check formatting
+prettier --write .     # fix formatting
+```
diff --git a/README.md b/README.md
index 3e0ddce..6b1af26 100644
--- a/README.md
+++ b/README.md
@@ -62,3 +62,7 @@ zendegi/
 - `pnpm run db:generate`: Generate database client/types
 - `pnpm run db:migrate`: Run database migrations
 - `pnpm run db:studio`: Open database studio UI
+
+## MCP
+
+claude mcp add --transport http zendegi-mcp http://localhost:3001/api/mcp