diff --git a/CLAUDE.md b/CLAUDE.md
index a82386a..33421ef 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -41,10 +41,10 @@ All frontend-backend communication goes through Tauri's typed IPC. The full pipe
 
 ### Backend (src-tauri/src/)
 
-- **`state.rs`** — `AppState`: holds `RwLock<HashMap<connection_id, PgPool>>`, read-only flags, config path. Connections default to read-only.
+- **`state.rs`** — `AppState`: holds connection pools (`pools`, `ch_clients`), read-only flags, DB flavors (PostgreSQL/Greenplum/ClickHouse), config path, chat-agent caches (`overview_cache`, `tables_by_db_cache`), MCP signal channels, and `ai_settings`. Connections default to read-only.
 - **`error.rs`** — `TuskError` enum with `thiserror`, serialized as string for IPC. `TuskResult<T>` type alias.
 - **`utils.rs`** — `escape_ident()` for safe SQL identifier quoting.
-- **`commands/`** — one module per domain (connections, queries, schema, data, export, management, history, saved_queries). Each function takes `State<'_, AppState>` and returns `TuskResult<T>`.
+- **`commands/`** — one module per domain (connections, queries, schema, data, export, management, history, saved_queries, ai, chat, chat_tools, memory, settings). Each function takes `State<'_, AppState>` and returns `TuskResult<T>`.
 - **`models/`** — serde-serializable structs matching TypeScript types.
 
 SQL safety: identifiers use `escape_ident()`, data queries use sqlx parameterized queries. Read-only mode wraps queries in `SET TRANSACTION READ ONLY` + `ROLLBACK`.
@@ -53,7 +53,8 @@ SQL safety: identifiers use `escape_ident()`, data queries use sqlx parameterize
 
 - **State**: Zustand store (`stores/app-store.ts`) — connections, active connection/database, tabs, read-only flags, pg version.
 - **Data fetching**: TanStack React Query hooks in `hooks/` — one hook per domain, wrapping `src/lib/tauri.ts` functions.
-- **UI**: shadcn/ui + Radix primitives, Tailwind CSS 4, dark mode via next-themes. SQL editor uses CodeMirror.
+- **AI chat**: tool-calling architecture — backend commands in `commands/chat.rs` / `commands/chat_tools.rs`, frontend tool definitions in `components/chat/tool-registry.ts`. Chat panel (`ChatPanel.tsx`) replaces the former inline `AiBar`, explain/fix, and chart-preview UIs.
+- **UI**: shadcn/ui + Radix primitives, Tailwind CSS 4, warm dark "Graphite & Honey" theme (IBM Plex Mono, honey accent). CodeMirror SQL editor with a custom theme from `src/lib/editor-theme.ts`.
 - **Layout**: resizable panels (sidebar + main area with tab bar).
 
 ### Stored Data
@@ -66,3 +67,4 @@ Connections are persisted to `~/.config/tusk/connections.json`. History and save
 - **Path alias**: `@` maps to `./src`
 - **Rust errors**: always use `TuskError` variants, never `unwrap()` in commands
 - **New PG types**: add conversion case in `pg_value_to_json()` in `commands/queries.rs`
+- **AI chat tools**: add Rust-side tool implementation in `commands/chat_tools.rs` and register it in both the backend dispatch (`ChatTool`) and the frontend `components/chat/tool-registry.ts` (schema, display component, card builder).