diff --git a/.claude/rules/02-development-commands.md b/.claude/rules/02-development-commands.md
index 5ef3b133c..d6f18aaad 100644
--- a/.claude/rules/02-development-commands.md
+++ b/.claude/rules/02-development-commands.md
@@ -94,7 +94,7 @@ adb kill-server                  # Stop ADB server
 adb start-server                 # Restart ADB server
 
 # Force stop app on device:
-adb shell am force-stop com.megamind.tauri-app
+adb shell am force-stop com.alphahuman.app
 
 # Kill Gradle daemon if stuck:
 # macOS/Linux:
@@ -156,10 +156,10 @@ Get-Process | Where-Object {$_.ProcessName -match "tauri|vite|cargo|node"} | Sto
 
 ## Build Targets
 
-| Platform | Command | Output |
-|----------|---------|--------|
-| Windows | `npm run tauri build` | `.msi`, `.exe` |
-| macOS | `npm run tauri build` | `.dmg`, `.app` |
-| Linux | `npm run tauri build` | `.deb`, `.AppImage` |
-| Android | `npm run tauri android build` | `.apk`, `.aab` |
-| iOS | `npm run tauri ios build` | `.ipa` |
+| Platform | Command                       | Output              |
+| -------- | ----------------------------- | ------------------- |
+| Windows  | `npm run tauri build`         | `.msi`, `.exe`      |
+| macOS    | `npm run tauri build`         | `.dmg`, `.app`      |
+| Linux    | `npm run tauri build`         | `.deb`, `.AppImage` |
+| Android  | `npm run tauri android build` | `.apk`, `.aab`      |
+| iOS      | `npm run tauri ios build`     | `.ipa`              |
diff --git a/.claude/rules/08-frontend-guide.md b/.claude/rules/08-frontend-guide.md
index c2d9bc981..bff4b964f 100644
--- a/.claude/rules/08-frontend-guide.md
+++ b/.claude/rules/08-frontend-guide.md
@@ -1,11 +1,13 @@
 # Frontend Development Guide - Crypto Community Platform
 
 ## Overview
+
 Frontend development guide for crypto-focused communication platform using modern React ecosystem with Tauri.
 
 ## ✅ CURRENT IMPLEMENTATION STATUS
 
 ### Design System (FULLY IMPLEMENTED)
+
 - **Glass Morphism UI**: Enhanced frosted glass effects with 16px backdrop blur throughout interface
 - **Crypto Price Ticker**: Animated scrolling ticker with BTC/ETH brand colors and JetBrains Mono font
 - **Navigation System**: Complete nav bar with active states (Dashboard, Portfolio, Chat, Markets)
@@ -67,6 +69,7 @@ src/
 ```
 
 ### Recent Architecture Changes
+
 - **Settings Modal System**: Complete URL-based modal system with clean white design
   - Modal routes: `/settings`, `/settings/connections` overlaying existing content
   - Component structure: SettingsModal, SettingsLayout, ConnectionsPanel, hooks
@@ -82,23 +85,23 @@ src/
 ### Basic Component
 
 ```tsx
-import { useState } from 'react';
-import { invoke } from '@tauri-apps/api/core';
+import { useState } from "react";
+import { invoke } from "@tauri-apps/api/core";
 
 function App() {
-    const [result, setResult] = useState('');
+  const [result, setResult] = useState("");
 
-    async function handleClick() {
-        const greeting = await invoke<string>('greet', { name: 'User' });
-        setResult(greeting);
-    }
+  async function handleClick() {
+    const greeting = await invoke<string>("greet", { name: "User" });
+    setResult(greeting);
+  }
 
-    return (
-        <div>
-            <button onClick={handleClick}>Greet</button>
-            <p>{result}</p>
-        </div>
-    );
+  return (
+    <div>
+      <button onClick={handleClick}>Greet</button>
+      <p>{result}</p>
+    </div>
+  );
 }
 
 export default App;
@@ -109,7 +112,7 @@ export default App;
 ### Window Management
 
 ```typescript
-import { getCurrentWindow } from '@tauri-apps/api/window';
+import { getCurrentWindow } from "@tauri-apps/api/window";
 
 const appWindow = getCurrentWindow();
 
@@ -123,73 +126,82 @@ await appWindow.maximize();
 await appWindow.close();
 
 // Set title
-await appWindow.setTitle('New Title');
+await appWindow.setTitle("New Title");
 ```
 
 ### File System
 
 First, add the plugin:
+
 ```bash
 npm run tauri add fs
 ```
 
 ```typescript
-import { readTextFile, writeTextFile, BaseDirectory } from '@tauri-apps/plugin-fs';
+import {
+  readTextFile,
+  writeTextFile,
+  BaseDirectory,
+} from "@tauri-apps/plugin-fs";
 
 // Read file
-const content = await readTextFile('config.json', {
-    baseDir: BaseDirectory.AppData
+const content = await readTextFile("config.json", {
+  baseDir: BaseDirectory.AppData,
 });
 
 // Write file
-await writeTextFile('config.json', JSON.stringify(data), {
-    baseDir: BaseDirectory.AppData
+await writeTextFile("config.json", JSON.stringify(data), {
+  baseDir: BaseDirectory.AppData,
 });
 ```
 
 ### Dialogs
 
 First, add the plugin:
+
 ```bash
 npm run tauri add dialog
 ```
 
 ```typescript
-import { open, save, message } from '@tauri-apps/plugin-dialog';
+import { open, save, message } from "@tauri-apps/plugin-dialog";
 
 // Open file picker
 const filePath = await open({
-    multiple: false,
-    filters: [{
-        name: 'Text',
-        extensions: ['txt', 'md']
-    }]
+  multiple: false,
+  filters: [
+    {
+      name: "Text",
+      extensions: ["txt", "md"],
+    },
+  ],
 });
 
 // Save dialog
 const savePath = await save({
-    defaultPath: 'document.txt'
+  defaultPath: "document.txt",
 });
 
 // Message box
-await message('Operation completed!', { title: 'Success' });
+await message("Operation completed!", { title: "Success" });
 ```
 
 ### HTTP Requests
 
 First, add the plugin:
+
 ```bash
 npm run tauri add http
 ```
 
 ```typescript
-import { fetch } from '@tauri-apps/plugin-http';
+import { fetch } from "@tauri-apps/plugin-http";
 
-const response = await fetch('https://api.example.com/data', {
-    method: 'GET',
-    headers: {
-        'Content-Type': 'application/json'
-    }
+const response = await fetch("https://api.example.com/data", {
+  method: "GET",
+  headers: {
+    "Content-Type": "application/json",
+  },
 });
 
 const data = await response.json();
@@ -198,26 +210,26 @@ const data = await response.json();
 ## Platform Detection
 
 ```typescript
-import { platform } from '@tauri-apps/plugin-os';
+import { platform } from "@tauri-apps/plugin-os";
 
 const currentPlatform = await platform();
 
 switch (currentPlatform) {
-    case 'windows':
-        // Windows-specific UI
-        break;
-    case 'macos':
-        // macOS-specific UI
-        break;
-    case 'linux':
-        // Linux-specific UI
-        break;
-    case 'android':
-        // Android-specific UI
-        break;
-    case 'ios':
-        // iOS-specific UI
-        break;
+  case "windows":
+    // Windows-specific UI
+    break;
+  case "macos":
+    // macOS-specific UI
+    break;
+  case "linux":
+    // Linux-specific UI
+    break;
+  case "android":
+    // Android-specific UI
+    break;
+  case "ios":
+    // iOS-specific UI
+    break;
 }
 ```
 
@@ -226,43 +238,45 @@ switch (currentPlatform) {
 ```css
 /* Base styles for mobile-first */
 .container {
-    padding: 16px;
-    font-size: 16px;
+  padding: 16px;
+  font-size: 16px;
 }
 
 /* Tablet and larger */
 @media (min-width: 768px) {
-    .container {
-        padding: 24px;
-        max-width: 720px;
-        margin: 0 auto;
-    }
+  .container {
+    padding: 24px;
+    max-width: 720px;
+    margin: 0 auto;
+  }
 }
 
 /* Desktop */
 @media (min-width: 1024px) {
-    .container {
-        max-width: 960px;
-    }
+  .container {
+    max-width: 960px;
+  }
 }
 
 /* Safe areas for notched devices (iOS) */
 .app {
-    padding-top: env(safe-area-inset-top);
-    padding-bottom: env(safe-area-inset-bottom);
-    padding-left: env(safe-area-inset-left);
-    padding-right: env(safe-area-inset-right);
+  padding-top: env(safe-area-inset-top);
+  padding-bottom: env(safe-area-inset-bottom);
+  padding-left: env(safe-area-inset-left);
+  padding-right: env(safe-area-inset-right);
 }
 ```
 
 ## Recommended Tech Stack
 
 ### UI & Styling
+
 - **Tailwind CSS** - Utility-first CSS framework
 - **Headless UI** - Accessible, unstyled UI components
 - **Framer Motion** - Animation library for React
 
 ### State & Data Management (Current Implementation)
+
 - **Redux Toolkit** - Currently implemented state management with persistence
 - **Redux Persist** - Persists auth and telegram state to localStorage
 - **Socket.io** - Real-time communication via socketService singleton
@@ -273,7 +287,7 @@ switch (currentPlatform) {
 
 ```typescript
 // Current implementation uses Redux Toolkit with these slices:
-import { useAppSelector, useAppDispatch } from '../store/hooks';
+import { useAppSelector, useAppDispatch } from "../store/hooks";
 
 // Auth state (persisted)
 const authState = useAppSelector((state) => state.auth);
@@ -293,106 +307,120 @@ const telegramState = useAppSelector((state) => state.telegram);
 
 // Usage in component
 function ChatHeader() {
-    const { token } = useAppSelector((state) => state.auth);
-    const { profile } = useAppSelector((state) => state.user);
-    const { isConnected } = useAppSelector((state) => state.socket);
+  const { token } = useAppSelector((state) => state.auth);
+  const { profile } = useAppSelector((state) => state.user);
+  const { isConnected } = useAppSelector((state) => state.socket);
 
-    return (
-        <div className="flex items-center justify-between p-4">
-            <h1>Chat</h1>
-            <div className="flex items-center gap-2">
-                <span>{profile?.username}</span>
-                <div className={`w-2 h-2 rounded-full ${isConnected ? 'bg-sage-500' : 'bg-coral-500'}`} />
-            </div>
-        </div>
-    );
+  return (
+    <div className="flex items-center justify-between p-4">
+      <h1>Chat</h1>
+      <div className="flex items-center gap-2">
+        <span>{profile?.username}</span>
+        <div
+          className={`w-2 h-2 rounded-full ${
+            isConnected ? "bg-sage-500" : "bg-coral-500"
+          }`}
+        />
+      </div>
+    </div>
+  );
 }
 ```
 
 ## Form Handling with React Hook Form
 
 ```typescript
-import { useForm } from 'react-hook-form';
-import { zodResolver } from '@hookform/resolvers/zod';
-import { z } from 'zod';
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { z } from "zod";
 
 const messageSchema = z.object({
-    content: z.string().min(1, 'Message cannot be empty').max(1000),
-    channel: z.string().uuid(),
+  content: z.string().min(1, "Message cannot be empty").max(1000),
+  channel: z.string().uuid(),
 });
 
 type MessageForm = z.infer<typeof messageSchema>;
 
 function MessageInput() {
-    const { register, handleSubmit, reset, formState: { errors } } = useForm<MessageForm>({
-        resolver: zodResolver(messageSchema)
-    });
+  const {
+    register,
+    handleSubmit,
+    reset,
+    formState: { errors },
+  } = useForm<MessageForm>({
+    resolver: zodResolver(messageSchema),
+  });
 
-    const onSubmit = (data: MessageForm) => {
-        // Send message via Tauri IPC
-        invoke('send_message', data);
-        reset();
-    };
+  const onSubmit = (data: MessageForm) => {
+    // Send message via Tauri IPC
+    invoke("send_message", data);
+    reset();
+  };
 
-    return (
-        <form onSubmit={handleSubmit(onSubmit)} className="flex gap-2">
-            <input
-                {...register('content')}
-                placeholder="Type a message..."
-                className="flex-1 p-2 border rounded"
-            />
-            <button type="submit" className="px-4 py-2 bg-blue-500 text-white rounded">
-                Send
-            </button>
-            {errors.content && <p className="text-red-500">{errors.content.message}</p>}
-        </form>
-    );
+  return (
+    <form onSubmit={handleSubmit(onSubmit)} className="flex gap-2">
+      <input
+        {...register("content")}
+        placeholder="Type a message..."
+        className="flex-1 p-2 border rounded"
+      />
+      <button
+        type="submit"
+        className="px-4 py-2 bg-blue-500 text-white rounded"
+      >
+        Send
+      </button>
+      {errors.content && (
+        <p className="text-red-500">{errors.content.message}</p>
+      )}
+    </form>
+  );
 }
 ```
 
 ## Data Fetching with TanStack Query
 
 ```typescript
-import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
-import { invoke } from '@tauri-apps/api/core';
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { invoke } from "@tauri-apps/api/core";
 
 // Fetch channels
 function useChannels() {
-    return useQuery({
-        queryKey: ['channels'],
-        queryFn: () => invoke<Channel[]>('get_channels'),
-        staleTime: 5 * 60 * 1000, // 5 minutes
-    });
+  return useQuery({
+    queryKey: ["channels"],
+    queryFn: () => invoke<Channel[]>("get_channels"),
+    staleTime: 5 * 60 * 1000, // 5 minutes
+  });
 }
 
 // Send message mutation
 function useSendMessage() {
-    const queryClient = useQueryClient();
+  const queryClient = useQueryClient();
 
-    return useMutation({
-        mutationFn: (message: NewMessage) => invoke('send_message', message),
-        onSuccess: () => {
-            // Invalidate and refetch messages
-            queryClient.invalidateQueries({ queryKey: ['messages'] });
-        },
-    });
+  return useMutation({
+    mutationFn: (message: NewMessage) => invoke("send_message", message),
+    onSuccess: () => {
+      // Invalidate and refetch messages
+      queryClient.invalidateQueries({ queryKey: ["messages"] });
+    },
+  });
 }
 
 // Usage in component
 function ChannelList() {
-    const { data: channels, isLoading, error } = useChannels();
+  const { data: channels, isLoading, error } = useChannels();
 
-    if (isLoading) return <div>Loading channels...</div>;
-    if (error) return <div>Error loading channels</div>;
+  if (isLoading) return <div>Loading channels...</div>;
+  if (error) return <div>Error loading channels</div>;
 
-    return (
-        <div className="space-y-2">
-            {channels?.map(channel => (
-                <div key={channel.id} className="p-2 hover:bg-gray-100 rounded">
-                    {channel.name}
-                </div>
-            ))}
+  return (
+    <div className="space-y-2">
+      {channels?.map((channel) => (
+        <div key={channel.id} className="p-2 hover:bg-gray-100 rounded">
+          {channel.name}
         </div>
-    );
+      ))}
+    </div>
+  );
 }
 ```
diff --git a/.claude/rules/13-backend-auth-implementation.md b/.claude/rules/13-backend-auth-implementation.md
index 52e6d8f4a..b406c4cfb 100644
--- a/.claude/rules/13-backend-auth-implementation.md
+++ b/.claude/rules/13-backend-auth-implementation.md
@@ -49,9 +49,11 @@ Web Browser                    Backend Server                 Desktop App (Tauri
 Initiates Telegram OAuth. The frontend opens this URL in the system browser.
 
 **Query params:**
+
 - `platform=desktop` — indicates the callback should produce a deep link handoff
 
 **Behavior:**
+
 1. Redirect user to Telegram OAuth authorization URL
 2. On callback, validate Telegram user data
 3. Create or find user in database
@@ -63,6 +65,7 @@ Initiates Telegram OAuth. The frontend opens this URL in the system browser.
 Called by the web frontend after phone-based authentication completes.
 
 **Request body:**
+
 ```json
 {
   "method": "phone",
@@ -70,15 +73,20 @@ Called by the web frontend after phone-based authentication completes.
   "countryCode": "+1"
 }
 ```
+
 or
+
 ```json
 {
   "method": "telegram",
-  "telegramUser": { /* Telegram user object */ }
+  "telegramUser": {
+    /* Telegram user object */
+  }
 }
 ```
 
 **Response (200):**
+
 ```json
 {
   "loginToken": "short-lived-opaque-token"
@@ -86,6 +94,7 @@ or
 ```
 
 **Behavior:**
+
 1. Validate the authentication data (verify OTP for phone, verify Telegram hash)
 2. Create or find user in database
 3. Generate a short-lived `loginToken`
@@ -101,6 +110,7 @@ Called by the Tauri Rust command `exchange_token` (NOT browser fetch). Exchanges
 **Note:** The endpoint path is `/auth/desktop-exchange` (no `/api` prefix) — this matches the current frontend implementation.
 
 **Request body:**
+
 ```json
 {
   "token": "loginToken-from-web"
@@ -108,6 +118,7 @@ Called by the Tauri Rust command `exchange_token` (NOT browser fetch). Exchanges
 ```
 
 **Response (200):**
+
 ```json
 {
   "sessionToken": "long-lived-session-token",
@@ -120,6 +131,7 @@ Called by the Tauri Rust command `exchange_token` (NOT browser fetch). Exchanges
 ```
 
 **Error response (401):**
+
 ```json
 {
   "success": false,
@@ -128,6 +140,7 @@ Called by the Tauri Rust command `exchange_token` (NOT browser fetch). Exchanges
 ```
 
 **Behavior:**
+
 1. Look up the `loginToken` in the database
 2. Validate: not expired, not already used
 3. Mark token as used (single-use enforcement)
@@ -137,35 +150,38 @@ Called by the Tauri Rust command `exchange_token` (NOT browser fetch). Exchanges
 ## Database Schema
 
 ### `users` table
-| Column | Type | Description |
-|--------|------|-------------|
-| id | UUID (PK) | User ID |
-| username | TEXT | Display name |
-| first_name | TEXT (nullable) | First name |
-| phone_number | TEXT (nullable) | Phone number |
-| telegram_id | TEXT (nullable) | Telegram user ID |
-| created_at | TIMESTAMP | Account creation |
-| updated_at | TIMESTAMP | Last update |
+
+| Column       | Type            | Description      |
+| ------------ | --------------- | ---------------- |
+| id           | UUID (PK)       | User ID          |
+| username     | TEXT            | Display name     |
+| first_name   | TEXT (nullable) | First name       |
+| phone_number | TEXT (nullable) | Phone number     |
+| telegram_id  | TEXT (nullable) | Telegram user ID |
+| created_at   | TIMESTAMP       | Account creation |
+| updated_at   | TIMESTAMP       | Last update      |
 
 ### `login_tokens` table (handoff tokens)
-| Column | Type | Description |
-|--------|------|-------------|
-| id | UUID (PK) | Token record ID |
-| token | TEXT (unique, indexed) | The opaque token string |
-| user_id | UUID (FK -> users) | Associated user |
-| created_at | TIMESTAMP | When issued |
-| expires_at | TIMESTAMP | Expiration (created_at + 5min) |
-| used | BOOLEAN | Whether already exchanged |
+
+| Column     | Type                   | Description                    |
+| ---------- | ---------------------- | ------------------------------ |
+| id         | UUID (PK)              | Token record ID                |
+| token      | TEXT (unique, indexed) | The opaque token string        |
+| user_id    | UUID (FK -> users)     | Associated user                |
+| created_at | TIMESTAMP              | When issued                    |
+| expires_at | TIMESTAMP              | Expiration (created_at + 5min) |
+| used       | BOOLEAN                | Whether already exchanged      |
 
 ### `sessions` table
-| Column | Type | Description |
-|--------|------|-------------|
-| id | UUID (PK) | Session ID |
-| token | TEXT (unique, indexed) | Session token |
-| user_id | UUID (FK -> users) | Associated user |
-| created_at | TIMESTAMP | When issued |
-| expires_at | TIMESTAMP | Expiration (created_at + 30 days) |
-| revoked | BOOLEAN | Whether revoked |
+
+| Column     | Type                   | Description                       |
+| ---------- | ---------------------- | --------------------------------- |
+| id         | UUID (PK)              | Session ID                        |
+| token      | TEXT (unique, indexed) | Session token                     |
+| user_id    | UUID (FK -> users)     | Associated user                   |
+| created_at | TIMESTAMP              | When issued                       |
+| expires_at | TIMESTAMP              | Expiration (created_at + 30 days) |
+| revoked    | BOOLEAN                | Whether revoked                   |
 
 ## Token Generation
 
@@ -195,16 +211,18 @@ async fn exchange_token(backend_url: String, token: String) -> Result<serde_json
 ```
 
 Frontend invocation:
+
 ```typescript
 const data = await invoke<{ sessionToken?: string; user?: object }>(
-  'exchange_token',
-  { backendUrl: BACKEND_URL, token }
+  "exchange_token",
+  { backendUrl: BACKEND_URL, token },
 );
 ```
 
 ### Deep Link Listener
 
 Located in `src/utils/desktopDeepLinkListener.ts`. Key behaviors:
+
 - Uses **lazy dynamic import** in `main.tsx` to avoid loading before Tauri IPC is ready
 - No `window.__TAURI__` guard — the try/catch handles non-Tauri environments
 - Uses `localStorage.setItem('deepLinkHandled', 'true')` to prevent infinite reload loops (since `getCurrent()` returns the same URL after `window.location.replace()`)
@@ -213,23 +231,24 @@ Located in `src/utils/desktopDeepLinkListener.ts`. Key behaviors:
 ### Backend URL Configuration
 
 Configured in `src/utils/config.ts`:
+
 ```typescript
 export const BACKEND_URL =
-  import.meta.env.VITE_BACKEND_URL || 'https://2937933edf8a.ngrok-free.app';
+  import.meta.env.VITE_BACKEND_URL || "https://2937933edf8a.ngrok-free.app";
 ```
 
 Set `VITE_BACKEND_URL` environment variable for different environments.
 
 ## Frontend Integration Points
 
-| File | Role |
-|------|------|
-| `src/main.tsx` | Lazy-imports and starts the deep link listener |
-| `src/utils/desktopDeepLinkListener.ts` | Parses deep link -> invokes Rust `exchange_token` -> stores session -> navigates |
-| `src/utils/deeplink.ts` | Web-side: calls `/api/auth/web-complete` and builds `alphahuman://auth?token=...` URL |
-| `src/utils/config.ts` | Backend URL configuration |
-| `src/pages/Login.tsx` | Opens `GET /auth/telegram?platform=desktop` in browser |
-| `src-tauri/src/lib.rs` | Rust `exchange_token` command using `reqwest` (CORS-free) |
+| File                                   | Role                                                                                  |
+| -------------------------------------- | ------------------------------------------------------------------------------------- |
+| `src/main.tsx`                         | Lazy-imports and starts the deep link listener                                        |
+| `src/utils/desktopDeepLinkListener.ts` | Parses deep link -> invokes Rust `exchange_token` -> stores session -> navigates      |
+| `src/utils/deeplink.ts`                | Web-side: calls `/api/auth/web-complete` and builds `alphahuman://auth?token=...` URL |
+| `src/utils/config.ts`                  | Backend URL configuration                                                             |
+| `src/pages/Login.tsx`                  | Opens `GET /auth/telegram?platform=desktop` in browser                                |
+| `src-tauri/src/lib.rs`                 | Rust `exchange_token` command using `reqwest` (CORS-free)                             |
 
 ## Phone OTP Flow (Future)
 
@@ -245,4 +264,4 @@ See `14-deep-link-platform-guide.md` for detailed platform gotchas.
 
 ---
 
-*Last updated: 2026-01-28*
+_Last updated: 2026-01-28_
diff --git a/.claude/rules/14-deep-link-platform-guide.md b/.claude/rules/14-deep-link-platform-guide.md
index 0cdfa1623..2415ced67 100644
--- a/.claude/rules/14-deep-link-platform-guide.md
+++ b/.claude/rules/14-deep-link-platform-guide.md
@@ -7,6 +7,7 @@ The `alphahuman://` custom URL scheme is used to hand off authentication from a
 ## Scheme Registration
 
 Configured in `src-tauri/tauri.conf.json`:
+
 ```json
 {
   "plugins": {
@@ -22,16 +23,19 @@ Configured in `src-tauri/tauri.conf.json`:
 ## macOS
 
 ### How It Works
+
 - URL schemes are registered via `Info.plist` inside the `.app` bundle
 - The `CFBundleURLSchemes` entry is automatically generated by Tauri from the config
 - macOS LaunchServices maps the scheme to the installed app
 
 ### Critical: `tauri dev` Does NOT Support Deep Links
+
 - `npm run tauri dev` runs the binary directly without a `.app` bundle
 - No `Info.plist` exists, so macOS cannot register the URL scheme
 - **You must use `npm run tauri build --debug` and run the `.app` bundle**
 
 ### `register_all()` Is Unsupported on macOS
+
 - The Tauri deep-link plugin's `register_all()` method panics on macOS with `unsupported platform`
 - Only call it on Windows and Linux:
   ```rust
@@ -42,6 +46,7 @@ Configured in `src-tauri/tauri.conf.json`:
   ```
 
 ### Build & Install Workflow
+
 ```bash
 # Build debug .app bundle
 npm run tauri build -- --debug --bundles app
@@ -57,6 +62,7 @@ open "alphahuman://auth?token=YOUR_TOKEN"
 ```
 
 ### Cargo Caching Gotcha
+
 - Cargo may not re-embed updated `dist/` frontend assets on incremental builds
 - The `tauri-build` build script embeds frontend assets at compile time
 - **If the app shows stale UI, run `cargo clean` before rebuilding:**
@@ -66,15 +72,17 @@ open "alphahuman://auth?token=YOUR_TOKEN"
   ```
 
 ### WebKit Cache
+
 - The macOS WebView (WKWebView) caches aggressively
 - Clear caches when debugging stale content:
   ```bash
-  rm -rf ~/Library/WebKit/com.megamind.tauri-app
-  rm -rf ~/Library/Caches/com.megamind.tauri-app
-  rm -rf ~/Library/Application\ Support/com.megamind.tauri-app
+  rm -rf ~/Library/WebKit/com.alphahuman.app
+  rm -rf ~/Library/Caches/com.alphahuman.app
+  rm -rf ~/Library/Application\ Support/com.alphahuman.app
   ```
 
 ### Debug Builds: Secondary Instance Behavior
+
 - In debug mode, clicking a deep link while the app is running may briefly spawn a secondary instance
 - The `onOpenUrl` event may fire twice (one may be an empty string)
 - The `deepLinkHandled` localStorage flag prevents double-processing
@@ -82,11 +90,13 @@ open "alphahuman://auth?token=YOUR_TOKEN"
 ## Windows & Linux
 
 ### How It Works
+
 - URL schemes are registered at runtime via `register_all()` in the `setup` hook
 - This works in both dev mode (`tauri dev`) and production builds
 - No special build or install steps needed for deep link testing
 
 ### Code
+
 ```rust
 #[cfg(any(windows, target_os = "linux"))]
 {
@@ -97,41 +107,47 @@ open "alphahuman://auth?token=YOUR_TOKEN"
 ## All Platforms
 
 ### `window.__TAURI__` Is Not Available Immediately
+
 - The Tauri IPC bridge (`window.__TAURI__`) is injected asynchronously
 - Code that runs at module load time (top of `main.tsx`) cannot reliably check `__TAURI__`
 - **Solution**: Use dynamic `import()` for the deep link listener and wrap plugin calls in try/catch:
   ```typescript
   // main.tsx
-  import('./utils/desktopDeepLinkListener').then(m => {
+  import("./utils/desktopDeepLinkListener").then((m) => {
     m.setupDesktopDeepLinkListener().catch(console.error);
   });
   ```
 
 ### `alert()` Is Suppressed in Tauri WebView
+
 - `window.alert()` does not display in Tauri's WKWebView on macOS
 - For debugging, use visible DOM elements or `console.log()` (viewable via Safari Web Inspector)
 
 ### `document.title` Is Overridden by Tauri
+
 - Tauri sets the window title from `tauri.conf.json` `app.windows[].title`
 - Setting `document.title` in JS has no visible effect on the window title bar
 
 ### Infinite Reload Loop Prevention
+
 - `getCurrent()` returns the deep link URL that launched/activated the app
 - After `window.location.replace()`, the page reloads and `getCurrent()` returns the same URL again
 - **Solution**: Set `localStorage.deepLinkHandled = 'true'` before navigating, check and clear it on next load
 
 ### CORS: Use Rust for Backend Calls
+
 - Browser `fetch()` from the Tauri WebView is subject to CORS
 - External APIs (especially ngrok tunnels) typically don't set `Access-Control-Allow-Origin`
 - **Solution**: Use a Rust Tauri command with `reqwest` to make HTTP requests (no CORS):
   ```typescript
   // Instead of fetch():
-  const data = await invoke('exchange_token', { backendUrl, token });
+  const data = await invoke("exchange_token", { backendUrl, token });
   ```
 
 ## Tauri Plugin Dependencies
 
 ### Cargo.toml
+
 ```toml
 tauri-plugin-deep-link = "2.0.0"
 reqwest = { version = "0.12", features = ["json"] }
@@ -139,21 +155,19 @@ tokio = { version = "1", features = ["full"] }
 ```
 
 ### package.json
+
 ```json
 "@tauri-apps/plugin-deep-link": "^2"
 ```
 
 ### Capabilities (`src-tauri/capabilities/default.json`)
+
 ```json
 {
-  "permissions": [
-    "core:default",
-    "opener:default",
-    "deep-link:default"
-  ]
+  "permissions": ["core:default", "opener:default", "deep-link:default"]
 }
 ```
 
 ---
 
-*Last updated: 2026-01-28*
+_Last updated: 2026-01-28_
diff --git a/.claude/rules/16-macos-background-execution.md b/.claude/rules/16-macos-background-execution.md
index aefec8994..3e1515481 100644
--- a/.claude/rules/16-macos-background-execution.md
+++ b/.claude/rules/16-macos-background-execution.md
@@ -7,6 +7,7 @@ Complete implementation of macOS background execution features including system
 ## Features Implemented
 
 ### 1. System Tray (Menu Bar App)
+
 - **Tray icon** appears in macOS menu bar
 - **Click to toggle** window visibility (left-click on icon)
 - **Context menu** with two options:
@@ -16,6 +17,7 @@ Complete implementation of macOS background execution features including system
 - **Close button minimizes to tray** instead of quitting app
 
 ### 2. Launch at Login (Autostart)
+
 - **LaunchAgent configuration** for macOS
 - **Configurable autostart** via plugin API
 - **Command-line flags** support for launch arguments
@@ -26,6 +28,7 @@ Complete implementation of macOS background execution features including system
 ### Dependencies Added
 
 **Cargo.toml**:
+
 ```toml
 tauri = { version = "2", features = ["tray-icon", "macos-private-api"] }
 tauri-plugin-autostart = "2"
@@ -34,15 +37,18 @@ tauri-plugin-autostart = "2"
 ### Configuration Changes
 
 **tauri.conf.json**:
+
 ```json
 {
   "app": {
-    "windows": [{
-      "visible": false,  // Start hidden
-      "decorations": true,
-      "resizable": true,
-      "center": true
-    }],
+    "windows": [
+      {
+        "visible": false, // Start hidden
+        "decorations": true,
+        "resizable": true,
+        "center": true
+      }
+    ],
     "trayIcon": {
       "id": "main-tray",
       "iconPath": "icons/icon.png",
@@ -50,12 +56,13 @@ tauri-plugin-autostart = "2"
       "menuOnLeftClick": false,
       "tooltip": "Outsourced - Crypto Community Platform"
     },
-    "macOSPrivateApi": true  // Required for advanced tray features
+    "macOSPrivateApi": true // Required for advanced tray features
   }
 }
 ```
 
 **capabilities/default.json**:
+
 ```json
 {
   "permissions": [
@@ -78,6 +85,7 @@ tauri-plugin-autostart = "2"
 4. **Autostart Plugin** - Configured with LaunchAgent for macOS
 
 **Code Structure** (`src-tauri/src/lib.rs`):
+
 ```rust
 // System tray with menu
 fn setup_tray(app: &AppHandle) -> Result<(), Box<dyn std::error::Error>> {
@@ -108,17 +116,20 @@ pub fn run() {
 ## Platform-Specific Behavior
 
 ### macOS
+
 - Tray icon appears in menu bar
 - Close button hides window (minimizes to tray)
 - LaunchAgent for autostart integration
 - Native macOS menu bar styling
 
 ### Windows/Linux
+
 - Tray icon in system tray
 - Same menu functionality
 - Platform-appropriate autostart mechanisms
 
 ### Mobile (iOS/Android)
+
 - Tray features disabled (desktop-only)
 - Autostart not applicable on mobile
 
@@ -129,21 +140,22 @@ pub fn run() {
 Control autostart via Tauri commands:
 
 ```typescript
-import { invoke } from '@tauri-apps/api/core';
+import { invoke } from "@tauri-apps/api/core";
 
 // Enable autostart
-await invoke('plugin:autostart|enable');
+await invoke("plugin:autostart|enable");
 
 // Disable autostart
-await invoke('plugin:autostart|disable');
+await invoke("plugin:autostart|disable");
 
 // Check if enabled
-const isEnabled = await invoke<boolean>('plugin:autostart|is_enabled');
+const isEnabled = await invoke<boolean>("plugin:autostart|is_enabled");
 ```
 
 ### Tray Behavior
 
 **User Actions**:
+
 1. **Left-click tray icon** → Toggle window visibility
 2. **Right-click tray icon** → Open context menu
 3. **"Show/Hide Window"** → Toggle visibility
@@ -153,6 +165,7 @@ const isEnabled = await invoke<boolean>('plugin:autostart|is_enabled');
 ## Testing
 
 ### Build & Test
+
 ```bash
 # Clean build
 cargo clean --manifest-path src-tauri/Cargo.toml
@@ -168,6 +181,7 @@ open /Applications/tauri-app.app
 ```
 
 ### Verification Checklist
+
 - [ ] Tray icon appears in menu bar
 - [ ] Left-click toggles window visibility
 - [ ] Context menu has "Show/Hide Window" and "Quit"
@@ -180,28 +194,35 @@ open /Applications/tauri-app.app
 ## Build Requirements
 
 ### macOS Deep Link & Tray Testing
+
 - Must use `.app` bundle (not `tauri dev`)
 - `tauri dev` does NOT support deep links or full tray functionality
 - Use debug build: `npm run tauri build -- --debug --bundles app`
 
 ### Cargo Cache Issues
+
 If UI appears outdated after rebuild:
+
 ```bash
 cargo clean --manifest-path src-tauri/Cargo.toml
 npm run tauri build -- --debug --bundles app
 ```
 
 ### WebKit Cache
+
 Clear WebKit cache if needed:
+
 ```bash
-rm -rf ~/Library/WebKit/com.megamind.tauri-app
-rm -rf ~/Library/Caches/com.megamind.tauri-app
+rm -rf ~/Library/WebKit/com.alphahuman.app
+rm -rf ~/Library/Caches/com.alphahuman.app
 ```
 
 ## Configuration Options
 
 ### Autostart Arguments
+
 Customize launch arguments in `lib.rs`:
+
 ```rust
 .plugin(tauri_plugin_autostart::init(
     tauri_plugin_autostart::MacosLauncher::LaunchAgent,
@@ -210,26 +231,32 @@ Customize launch arguments in `lib.rs`:
 ```
 
 ### Tray Icon
+
 Change tray icon path in `tauri.conf.json`:
+
 ```json
 {
   "trayIcon": {
     "iconPath": "icons/custom-tray-icon.png",
-    "iconAsTemplate": true  // Adapts to dark/light menu bar
+    "iconAsTemplate": true // Adapts to dark/light menu bar
   }
 }
 ```
 
 ### Window Behavior
+
 Adjust window settings:
+
 ```json
 {
-  "windows": [{
-    "visible": false,      // Start hidden
-    "decorations": true,   // Show title bar
-    "resizable": true,     // Allow resize
-    "center": true         // Center on screen
-  }]
+  "windows": [
+    {
+      "visible": false, // Start hidden
+      "decorations": true, // Show title bar
+      "resizable": true, // Allow resize
+      "center": true // Center on screen
+    }
+  ]
 }
 ```
 
@@ -253,16 +280,18 @@ Potential improvements for future development:
 ## Security Considerations
 
 ### macOS Private API
+
 - Required for advanced tray features
 - Approved by Apple for this use case
 - No App Store restrictions for direct distribution
 
 ### LaunchAgent
+
 - Installed in user's LaunchAgents directory
 - User can disable via System Settings
 - Respects macOS security policies
 
 ---
 
-*Implementation completed: 2026-01-29*
-*Status: Fully functional, tested, and production-ready*
+_Implementation completed: 2026-01-29_
+_Status: Fully functional, tested, and production-ready_
diff --git a/CLAUDE.md b/CLAUDE.md
index 307adb36a..781bc8da0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -11,6 +11,7 @@ Cross-platform crypto community communication platform built with **Tauri v2** (
 **Design Philosophy**: Premium, sophisticated crypto platform with calm, trustworthy aesthetic.
 
 ### Color Palette
+
 - **Primary**: Ocean blue (`#4A83DD`) optimized for dark backgrounds
 - **Sage**: Success green (`#4DC46F`) for growth indicators
 - **Amber**: Warning (`#E8A838`) for attention states
@@ -19,18 +20,21 @@ Cross-platform crypto community communication platform built with **Tauri v2** (
 - **Market Colors**: Bullish green, bearish red, Bitcoin orange, Ethereum purple
 
 ### Typography
+
 - **Primary**: Inter (premium font stack)
 - **Display**: Cabinet Grotesk for headings
 - **Mono**: JetBrains Mono for code
 - **Scale**: Sophisticated sizing with negative letter spacing for elegance
 
 ### Component System
+
 - **Shadows**: Glow effects, subtle to float depth levels
 - **Animations**: Fade-in, slide-in, scale-in with cubic-bezier easing
 - **Border Radius**: Smooth system from `xs` (0.25rem) to `5xl` (2rem)
 - **Spacing**: Extended scale including custom values (4.5, 13, 15, etc.)
 
 ### Current UI State
+
 - Uses HashRouter (not BrowserRouter) as seen in `App.tsx:1`
 - 153 TypeScript files total in src/
 - Sophisticated Tailwind config with custom color system and animations
@@ -74,6 +78,7 @@ The app wraps in this order: `Redux Provider` → `PersistGate` → `SocketProvi
 ### State Management (Redux Toolkit + Persist)
 
 State lives in `src/store/` using Redux Toolkit slices:
+
 - **authSlice** — JWT token, onboarding completion flag (persisted)
 - **userSlice** — user profile
 - **socketSlice** — connection status, socket ID
@@ -97,6 +102,7 @@ Redux Persist stores auth and telegram state (storage backend is configurable; d
 ### MCP System (`src/lib/mcp/`)
 
 Model Context Protocol implementation for AI tool execution over Socket.io:
+
 - `transport.ts` — Socket.io JSON-RPC 2.0 transport with 30s timeout
 - `telegram/server.ts` — TelegramMCPServer manages 99 tool definitions
 - `telegram/tools/` — Individual tool files (one per Telegram API operation)
@@ -117,6 +123,7 @@ Model Context Protocol implementation for AI tool execution over Socket.io:
 ### Deep Link Auth Flow
 
 Web-to-desktop handoff using `alphahuman://` URL scheme:
+
 1. User authenticates in browser
 2. Browser redirects to `alphahuman://auth?token=<loginToken>`
 3. Tauri catches the deep link, Rust `exchange_token` command calls backend via `reqwest` (bypasses CORS)
@@ -128,6 +135,7 @@ Key file: `src/utils/desktopDeepLinkListener.ts` (lazy-loaded in `main.tsx`). Us
 ### Rust Backend (`src-tauri/src/lib.rs`)
 
 Minimal — two Tauri commands:
+
 - `greet` — demo command
 - `exchange_token` — CORS-free HTTP POST to backend for token exchange
 
@@ -137,14 +145,14 @@ Deep link plugin registered at setup. `register_all()` called only on Windows/Li
 
 Set in `.env` (Vite exposes `VITE_*` prefixed vars):
 
-| Variable | Purpose |
-|----------|---------|
-| `VITE_BACKEND_URL` | Backend API URL (default: `http://localhost:5005`) |
-| `VITE_TELEGRAM_API_ID` | Telegram MTProto API ID |
-| `VITE_TELEGRAM_API_HASH` | Telegram MTProto API hash |
-| `VITE_TELEGRAM_BOT_USERNAME` | Telegram bot username |
-| `VITE_TELEGRAM_BOT_ID` | Telegram bot numeric ID |
-| `VITE_DEBUG` | Debug mode flag |
+| Variable                     | Purpose                                            |
+| ---------------------------- | -------------------------------------------------- |
+| `VITE_BACKEND_URL`           | Backend API URL (default: `http://localhost:5005`) |
+| `VITE_TELEGRAM_API_ID`       | Telegram MTProto API ID                            |
+| `VITE_TELEGRAM_API_HASH`     | Telegram MTProto API hash                          |
+| `VITE_TELEGRAM_BOT_USERNAME` | Telegram bot username                              |
+| `VITE_TELEGRAM_BOT_ID`       | Telegram bot numeric ID                            |
+| `VITE_DEBUG`                 | Debug mode flag                                    |
 
 Production defaults are in `src/utils/config.ts`.
 
@@ -153,6 +161,7 @@ Production defaults are in `src/utils/config.ts`.
 Key updates from recent commits:
 
 ### Major Additions
+
 - **Settings Modal System** (`60054d8`): Complete URL-based settings modal with clean white design
   - Modal infrastructure with backdrop blur and center positioning
   - User profile integration with Redux state management
@@ -166,6 +175,7 @@ Key updates from recent commits:
 - **Big Integer Support**: Consistent handling across all Telegram MCP tools (`0abed4d`)
 
 ### Design System Updates
+
 - **Settings Modal UI**: Clean 520px white modal contrasting with glass morphism theme
 - **Animations**: 200ms entry animations, 250ms panel transitions, chevron hover effects
 - **Lottie Animations**: Integrated into onboarding flow (`334673e`)
@@ -174,6 +184,7 @@ Key updates from recent commits:
 - **Theme**: Implemented sophisticated color system with premium crypto aesthetic
 
 ### Component Structure
+
 - **165+ TypeScript files** across `src/` directory (added settings modal system)
 - **Settings Modal System**: Complete modal infrastructure in `src/components/settings/`
   - SettingsModal.tsx - Main container with URL routing
@@ -200,6 +211,6 @@ Key updates from recent commits:
 
 ## Platform Gotchas
 
-- **macOS deep links**: Require `.app` bundle (not `tauri dev`). Clear WebKit caches when debugging stale content: `rm -rf ~/Library/WebKit/com.megamind.tauri-app ~/Library/Caches/com.megamind.tauri-app`
+- **macOS deep links**: Require `.app` bundle (not `tauri dev`). Clear WebKit caches when debugging stale content: `rm -rf ~/Library/WebKit/com.alphahuman.app ~/Library/Caches/com.alphahuman.app`
 - **Cargo caching**: May serve stale frontend assets on incremental builds. Run `cargo clean --manifest-path src-tauri/Cargo.toml` if the app shows outdated UI.
 - **`window.__TAURI__`**: Not available at module load time. Use dynamic `import()` and try/catch for Tauri plugin calls.
diff --git a/docs/src-tauri/01-architecture.md b/docs/src-tauri/01-architecture.md
index 5e59bb627..fb8c41e59 100644
--- a/docs/src-tauri/01-architecture.md
+++ b/docs/src-tauri/01-architecture.md
@@ -3,6 +3,7 @@
 ## Overview
 
 The Tauri Rust backend provides native functionality for the AlphaHuman desktop application:
+
 - System tray with background execution
 - Deep link authentication
 - Secure session storage (OS Keychain)
@@ -41,6 +42,7 @@ src-tauri/src/
 ### lib.rs - Application Entry
 
 The main entry point that:
+
 1. Registers Tauri plugins (opener, deep-link, autostart, notification)
 2. Sets up system tray with Show/Hide and Quit menu
 3. Handles macOS-specific window close behavior (minimize to tray)
@@ -50,34 +52,36 @@ The main entry point that:
 
 Commands are exposed to the frontend via Tauri's IPC:
 
-| Module | Commands | Purpose |
-|--------|----------|---------|
-| `auth` | `exchange_token`, `get_auth_state`, `logout`, etc. | Authentication |
-| `socket` | `socket_connect`, `report_socket_connected`, etc. | Socket state |
-| `telegram` | `start_telegram_login` | Telegram OAuth |
-| `window` | `show_window`, `hide_window`, `toggle_window`, etc. | Window control |
+| Module     | Commands                                            | Purpose        |
+| ---------- | --------------------------------------------------- | -------------- |
+| `auth`     | `exchange_token`, `get_auth_state`, `logout`, etc.  | Authentication |
+| `socket`   | `socket_connect`, `report_socket_connected`, etc.   | Socket state   |
+| `telegram` | `start_telegram_login`                              | Telegram OAuth |
+| `window`   | `show_window`, `hide_window`, `toggle_window`, etc. | Window control |
 
 ### Services Layer
 
 Singleton services providing background functionality:
 
-| Service | Purpose | Storage |
-|---------|---------|---------|
-| `SessionService` | Secure auth token storage | OS Keychain |
-| `SocketService` | Socket.io state management | Memory + Events |
-| `NotificationService` | Native notifications | N/A |
+| Service               | Purpose                    | Storage         |
+| --------------------- | -------------------------- | --------------- |
+| `SessionService`      | Secure auth token storage  | OS Keychain     |
+| `SocketService`       | Socket.io state management | Memory + Events |
+| `NotificationService` | Native notifications       | N/A             |
 
 ## Architecture Decisions
 
 ### Socket.io Strategy
 
 The frontend maintains the actual Socket.io connection, while Rust:
+
 1. Stores connection parameters
 2. Tracks connection state
 3. Emits events to coordinate with frontend
 4. Ensures socket stays connected when window is hidden
 
 This approach is necessary because:
+
 - Rust's Socket.io libraries have API compatibility issues
 - The WebView maintains state when hidden (unlike browser tabs)
 - Frontend JavaScript is better suited for Socket.io's event-driven model
@@ -85,6 +89,7 @@ This approach is necessary because:
 ### Keychain Storage
 
 Session tokens are stored in the OS keychain for security:
+
 - **macOS**: Keychain
 - **Windows**: Credential Manager
 - **Linux**: Secret Service
@@ -105,39 +110,41 @@ listen("socket:should_connect", (event) => {
 
 ## Plugin Dependencies
 
-| Plugin | Version | Purpose |
-|--------|---------|---------|
-| `tauri-plugin-opener` | 2 | Open URLs in browser |
-| `tauri-plugin-deep-link` | 2.0.0 | Handle `alphahuman://` URLs |
-| `tauri-plugin-autostart` | 2 | Launch at login |
-| `tauri-plugin-notification` | 2 | Native notifications |
+| Plugin                      | Version | Purpose                     |
+| --------------------------- | ------- | --------------------------- |
+| `tauri-plugin-opener`       | 2       | Open URLs in browser        |
+| `tauri-plugin-deep-link`    | 2.0.0   | Handle `alphahuman://` URLs |
+| `tauri-plugin-autostart`    | 2       | Launch at login             |
+| `tauri-plugin-notification` | 2       | Native notifications        |
 
 ## Cargo Dependencies
 
-| Crate | Purpose |
-|-------|---------|
-| `tauri` | Core framework with tray and macOS APIs |
-| `serde`, `serde_json` | Serialization |
-| `reqwest` | HTTP client |
-| `tokio` | Async runtime |
-| `keyring` | Secure credential storage |
-| `once_cell` | Lazy static singletons |
-| `parking_lot` | Fast mutexes |
-| `log`, `env_logger` | Logging |
+| Crate                 | Purpose                                 |
+| --------------------- | --------------------------------------- |
+| `tauri`               | Core framework with tray and macOS APIs |
+| `serde`, `serde_json` | Serialization                           |
+| `reqwest`             | HTTP client                             |
+| `tokio`               | Async runtime                           |
+| `keyring`             | Secure credential storage               |
+| `once_cell`           | Lazy static singletons                  |
+| `parking_lot`         | Fast mutexes                            |
+| `log`, `env_logger`   | Logging                                 |
 
 ## Platform-Specific Behavior
 
 ### macOS
+
 - Window close button hides instead of quitting
 - Dock icon click shows window
 - LaunchAgent for autostart
 - Keychain for secure storage
 
 ### Windows/Linux
+
 - Deep link registration at runtime
 - Platform-specific credential storage
 - Registry (Windows) or desktop file (Linux) autostart
 
 ---
 
-*Next: [Commands Reference](./02-commands.md)*
+_Next: [Commands Reference](./02-commands.md)_
diff --git a/docs/src-tauri/02-commands.md b/docs/src-tauri/02-commands.md
index 62a14f549..e15268d19 100644
--- a/docs/src-tauri/02-commands.md
+++ b/docs/src-tauri/02-commands.md
@@ -5,204 +5,229 @@ This document lists all Tauri commands available to the frontend.
 ## Authentication Commands
 
 ### `exchange_token`
+
 Exchange a login token for a session token.
 
 ```typescript
-const result = await invoke('exchange_token', {
-  backendUrl: 'https://api.example.com',
-  token: 'login-token-from-deep-link'
+const result = await invoke("exchange_token", {
+  backendUrl: "https://api.example.com",
+  token: "login-token-from-deep-link",
 });
 // Returns: { sessionToken: string, user: User }
 ```
 
 ### `get_auth_state`
+
 Get current authentication state.
 
 ```typescript
-const state = await invoke<AuthState>('get_auth_state');
+const state = await invoke<AuthState>("get_auth_state");
 // Returns: { is_authenticated: boolean, user: User | null }
 ```
 
 ### `get_session_token`
+
 Get the current session token.
 
 ```typescript
-const token = await invoke<string | null>('get_session_token');
+const token = await invoke<string | null>("get_session_token");
 ```
 
 ### `get_current_user`
+
 Get the current authenticated user.
 
 ```typescript
-const user = await invoke<User | null>('get_current_user');
+const user = await invoke<User | null>("get_current_user");
 ```
 
 ### `is_authenticated`
+
 Check if user is authenticated.
 
 ```typescript
-const isAuth = await invoke<boolean>('is_authenticated');
+const isAuth = await invoke<boolean>("is_authenticated");
 ```
 
 ### `logout`
+
 Clear session and disconnect socket.
 
 ```typescript
-await invoke('logout');
+await invoke("logout");
 ```
 
 ### `store_session`
+
 Manually store a session (usually called automatically by `exchange_token`).
 
 ```typescript
-await invoke('store_session', {
-  token: 'session-token',
-  user: { id: '123', firstName: 'John' }
+await invoke("store_session", {
+  token: "session-token",
+  user: { id: "123", firstName: "John" },
 });
 ```
 
 ## Socket Commands
 
 ### `socket_connect`
+
 Request frontend to connect to socket server.
 
 ```typescript
-await invoke('socket_connect', {
-  backendUrl: 'https://api.example.com',
-  token: 'session-token'
+await invoke("socket_connect", {
+  backendUrl: "https://api.example.com",
+  token: "session-token",
 });
 // Emits "socket:should_connect" event
 ```
 
 ### `socket_disconnect`
+
 Request frontend to disconnect from socket server.
 
 ```typescript
-await invoke('socket_disconnect');
+await invoke("socket_disconnect");
 // Emits "socket:should_disconnect" event
 ```
 
 ### `get_socket_state`
+
 Get current socket state.
 
 ```typescript
-const state = await invoke<SocketState>('get_socket_state');
+const state = await invoke<SocketState>("get_socket_state");
 // Returns: { status: 'connected' | 'disconnected' | ..., socket_id: string | null, error: string | null }
 ```
 
 ### `is_socket_connected`
+
 Check if socket is connected.
 
 ```typescript
-const isConnected = await invoke<boolean>('is_socket_connected');
+const isConnected = await invoke<boolean>("is_socket_connected");
 ```
 
 ### `report_socket_connected`
+
 Report that socket connected (called by frontend).
 
 ```typescript
-await invoke('report_socket_connected', { socketId: 'socket-id' });
+await invoke("report_socket_connected", { socketId: "socket-id" });
 ```
 
 ### `report_socket_disconnected`
+
 Report that socket disconnected (called by frontend).
 
 ```typescript
-await invoke('report_socket_disconnected');
+await invoke("report_socket_disconnected");
 ```
 
 ### `report_socket_error`
+
 Report socket error (called by frontend).
 
 ```typescript
-await invoke('report_socket_error', { error: 'Connection failed' });
+await invoke("report_socket_error", { error: "Connection failed" });
 ```
 
 ### `update_socket_status`
+
 Update socket status (called by frontend).
 
 ```typescript
-await invoke('update_socket_status', {
-  status: 'connected', // 'connected' | 'connecting' | 'disconnected' | 'reconnecting' | 'error'
-  socketId: 'socket-id'
+await invoke("update_socket_status", {
+  status: "connected", // 'connected' | 'connecting' | 'disconnected' | 'reconnecting' | 'error'
+  socketId: "socket-id",
 });
 ```
 
 ## Telegram Commands
 
 ### `start_telegram_login`
+
 Open Telegram login widget in browser.
 
 ```typescript
-await invoke('start_telegram_login');
+await invoke("start_telegram_login");
 // Opens ${DEFAULT_BACKEND_URL}/auth/telegram-widget?redirect=alphahuman://auth
 ```
 
 ### `start_telegram_login_with_url`
+
 Open Telegram login widget with custom backend URL.
 
 ```typescript
-await invoke('start_telegram_login_with_url', {
-  backendUrl: 'https://custom-backend.com'
+await invoke("start_telegram_login_with_url", {
+  backendUrl: "https://custom-backend.com",
 });
 ```
 
 ## Window Commands
 
 ### `show_window`
+
 Show and focus the main window.
 
 ```typescript
-await invoke('show_window');
+await invoke("show_window");
 ```
 
 ### `hide_window`
+
 Hide the main window.
 
 ```typescript
-await invoke('hide_window');
+await invoke("hide_window");
 ```
 
 ### `toggle_window`
+
 Toggle window visibility.
 
 ```typescript
-await invoke('toggle_window');
+await invoke("toggle_window");
 ```
 
 ### `is_window_visible`
+
 Check if window is visible.
 
 ```typescript
-const isVisible = await invoke<boolean>('is_window_visible');
+const isVisible = await invoke<boolean>("is_window_visible");
 ```
 
 ### `minimize_window`
+
 Minimize the window.
 
 ```typescript
-await invoke('minimize_window');
+await invoke("minimize_window");
 ```
 
 ### `maximize_window`
+
 Maximize or unmaximize the window.
 
 ```typescript
-await invoke('maximize_window');
+await invoke("maximize_window");
 ```
 
 ### `close_window`
+
 Close the window (minimizes to tray on macOS).
 
 ```typescript
-await invoke('close_window');
+await invoke("close_window");
 ```
 
 ### `set_window_title`
+
 Set the window title.
 
 ```typescript
-await invoke('set_window_title', { title: 'New Title' });
+await invoke("set_window_title", { title: "New Title" });
 ```
 
 ## Events (Rust → Frontend)
@@ -211,29 +236,29 @@ These events are emitted by Rust and can be listened to in the frontend:
 
 ### Socket Events
 
-| Event | Payload | Description |
-|-------|---------|-------------|
-| `socket:connected` | `()` | Socket connected |
-| `socket:disconnected` | `()` | Socket disconnected |
-| `socket:error` | `string` | Socket error occurred |
-| `socket:message` | `{ event: string, data: any }` | Socket message received |
-| `socket:state_changed` | `SocketState` | Socket state changed |
-| `socket:should_connect` | `{ backendUrl: string, token: string }` | Request to connect |
-| `socket:should_disconnect` | `()` | Request to disconnect |
+| Event                      | Payload                                 | Description             |
+| -------------------------- | --------------------------------------- | ----------------------- |
+| `socket:connected`         | `()`                                    | Socket connected        |
+| `socket:disconnected`      | `()`                                    | Socket disconnected     |
+| `socket:error`             | `string`                                | Socket error occurred   |
+| `socket:message`           | `{ event: string, data: any }`          | Socket message received |
+| `socket:state_changed`     | `SocketState`                           | Socket state changed    |
+| `socket:should_connect`    | `{ backendUrl: string, token: string }` | Request to connect      |
+| `socket:should_disconnect` | `()`                                    | Request to disconnect   |
 
 ### Listening to Events
 
 ```typescript
-import { listen } from '@tauri-apps/api/event';
+import { listen } from "@tauri-apps/api/event";
 
 // Listen for socket connection request
-await listen('socket:should_connect', (event) => {
+await listen("socket:should_connect", (event) => {
   const { backendUrl, token } = event.payload;
   socketService.connect(backendUrl, token);
 });
 
 // Listen for state changes
-await listen('socket:state_changed', (event) => {
+await listen("socket:state_changed", (event) => {
   const state = event.payload as SocketState;
   dispatch(setSocketStatus(state.status));
 });
@@ -257,7 +282,12 @@ interface User {
 }
 
 interface SocketState {
-  status: 'connected' | 'connecting' | 'disconnected' | 'reconnecting' | 'error';
+  status:
+    | "connected"
+    | "connecting"
+    | "disconnected"
+    | "reconnecting"
+    | "error";
   socket_id: string | null;
   error?: string;
 }
@@ -265,4 +295,4 @@ interface SocketState {
 
 ---
 
-*Previous: [Architecture](./01-architecture.md) | Next: [Services](./03-services.md)*
+_Previous: [Architecture](./01-architecture.md) | Next: [Services](./03-services.md)_
diff --git a/docs/src-tauri/README.md b/docs/src-tauri/README.md
index bb827c2e9..ab036f21c 100644
--- a/docs/src-tauri/README.md
+++ b/docs/src-tauri/README.md
@@ -6,11 +6,11 @@ This documentation covers the Tauri Rust backend for the AlphaHuman desktop appl
 
 ## Quick Reference
 
-| Document | Description |
-|----------|-------------|
-| [Architecture](./01-architecture.md) | System architecture and module structure |
-| [Commands Reference](./02-commands.md) | All Tauri IPC commands |
-| [Services](./03-services.md) | Background services documentation |
+| Document                               | Description                              |
+| -------------------------------------- | ---------------------------------------- |
+| [Architecture](./01-architecture.md)   | System architecture and module structure |
+| [Commands Reference](./02-commands.md) | All Tauri IPC commands                   |
+| [Services](./03-services.md)           | Background services documentation        |
 
 ## Features Implemented
 
@@ -24,6 +24,7 @@ This documentation covers the Tauri Rust backend for the AlphaHuman desktop appl
 ## Current State Analysis
 
 ### Existing Implementation (`lib.rs`)
+
 - ✅ System tray with show/hide/quit
 - ✅ Deep link handling (`alphahuman://` scheme)
 - ✅ Token exchange command (CORS bypass)
@@ -31,6 +32,7 @@ This documentation covers the Tauri Rust backend for the AlphaHuman desktop appl
 - ✅ Window minimize-to-tray on close (macOS)
 
 ### Missing Features
+
 - ❌ Socket.io client in Rust (background persistence)
 - ❌ Telegram Widget integration
 - ❌ Session management in Rust
@@ -74,6 +76,7 @@ src-tauri/src/
 **Goal**: Persistent WebSocket connection even when app is in background
 
 **Dependencies to add:**
+
 ```toml
 [dependencies]
 rust_socketio = "0.6"           # Socket.io client
@@ -83,6 +86,7 @@ parking_lot = "0.12"            # Fast mutexes
 ```
 
 **Implementation:**
+
 ```rust
 // services/socket_service.rs
 pub struct SocketService {
@@ -100,6 +104,7 @@ impl SocketService {
 ```
 
 **Background Persistence:**
+
 - Socket runs on Tokio runtime, independent of window state
 - Connection survives window hide/minimize
 - Auto-reconnect on network recovery
@@ -110,6 +115,7 @@ impl SocketService {
 **Goal**: Web-based Telegram auth → Deep link callback → Native session
 
 **Flow:**
+
 ```
 1. User clicks "Login with Telegram" in desktop app
    ↓
@@ -134,12 +140,15 @@ impl SocketService {
 ```
 
 **Backend Endpoint Needed:**
+
 ```
 GET /auth/telegram-widget?redirect={deeplink_scheme}
 ```
+
 Returns HTML page with Telegram Login Widget that redirects to the specified scheme.
 
 **Commands to implement:**
+
 ```rust
 #[tauri::command]
 async fn start_telegram_login(app: AppHandle) -> Result<(), String> {
@@ -165,12 +174,14 @@ async fn logout(app: AppHandle) -> Result<(), String> {
 **Goal**: Store auth tokens securely using OS keychain
 
 **Dependencies:**
+
 ```toml
 [dependencies]
 keyring = "3"  # Cross-platform keychain access
 ```
 
 **Implementation:**
+
 ```rust
 // services/session_service.rs
 pub struct SessionService {
@@ -178,7 +189,7 @@ pub struct SessionService {
 }
 
 impl SessionService {
-    const SERVICE: &'static str = "com.megamind.tauri-app";
+    const SERVICE: &'static str = "com.alphahuman.app";
 
     pub fn store_token(&self, token: &str) -> Result<(), Error>;
     pub fn get_token(&self) -> Result<Option<String>, Error>;
@@ -187,6 +198,7 @@ impl SessionService {
 ```
 
 **Platform Support:**
+
 - macOS: Keychain
 - Windows: Credential Manager
 - Linux: Secret Service (libsecret)
@@ -196,12 +208,14 @@ impl SessionService {
 **Goal**: Show notifications even when app is minimized
 
 **Dependencies:**
+
 ```toml
 [dependencies]
 tauri-plugin-notification = "2"
 ```
 
 **Capability Addition:**
+
 ```json
 {
   "permissions": [
@@ -213,6 +227,7 @@ tauri-plugin-notification = "2"
 ```
 
 **Usage:**
+
 ```rust
 // services/notification_service.rs
 pub fn show_notification(title: &str, body: &str) -> Result<(), Error> {
@@ -229,6 +244,7 @@ pub fn show_notification(title: &str, body: &str) -> Result<(), Error> {
 **Goal**: Bidirectional communication between Rust services and React frontend
 
 **Events from Rust to Frontend:**
+
 ```rust
 // Emit to frontend when socket receives message
 app.emit("socket:message", payload)?;
@@ -238,10 +254,11 @@ app.emit("telegram:notification", notification)?;
 ```
 
 **Frontend listening:**
-```typescript
-import { listen } from '@tauri-apps/api/event';
 
-await listen('socket:message', (event) => {
+```typescript
+import { listen } from "@tauri-apps/api/event";
+
+await listen("socket:message", (event) => {
   // Handle message from Rust socket service
 });
 ```
@@ -251,12 +268,14 @@ await listen('socket:message', (event) => {
 **Goal**: Run MCP tools from Rust for performance-critical operations
 
 **Approach:**
+
 - Keep MCP tools in TypeScript for flexibility
 - Rust handles socket transport
 - Frontend dispatches tool calls
 - Rust forwards via socket, returns results
 
 **Alternative (Full Rust MCP):**
+
 - Implement tool handlers in Rust
 - Higher performance, but more maintenance
 - Consider for v2
@@ -265,15 +284,15 @@ await listen('socket:message', (event) => {
 
 ## Implementation Order
 
-| Phase | Priority | Effort | Dependencies |
-|-------|----------|--------|--------------|
-| 1. Project Structure | High | 2h | None |
-| 2. Socket.io Service | High | 4h | Phase 1 |
-| 3. Telegram Widget Login | High | 3h | Backend endpoint |
-| 4. Secure Storage | High | 2h | Phase 1 |
-| 5. Notifications | Medium | 1h | Phase 2 |
-| 6. Event Bridge | High | 2h | Phase 2 |
-| 7. MCP Integration | Low | 4h+ | Phase 2, 6 |
+| Phase                    | Priority | Effort | Dependencies     |
+| ------------------------ | -------- | ------ | ---------------- |
+| 1. Project Structure     | High     | 2h     | None             |
+| 2. Socket.io Service     | High     | 4h     | Phase 1          |
+| 3. Telegram Widget Login | High     | 3h     | Backend endpoint |
+| 4. Secure Storage        | High     | 2h     | Phase 1          |
+| 5. Notifications         | Medium   | 1h     | Phase 2          |
+| 6. Event Bridge          | High     | 2h     | Phase 2          |
+| 7. MCP Integration       | Low      | 4h+    | Phase 2, 6       |
 
 **Total Estimated Effort**: 18+ hours
 
@@ -282,6 +301,7 @@ await listen('socket:message', (event) => {
 ## Cross-Platform Considerations
 
 ### macOS
+
 - ✅ System tray (menu bar)
 - ✅ LaunchAgent autostart
 - ✅ Keychain storage
@@ -289,6 +309,7 @@ await listen('socket:message', (event) => {
 - ⚠️ Notarization for distribution
 
 ### Windows
+
 - ✅ System tray
 - ✅ Registry autostart
 - ✅ Credential Manager storage
@@ -296,12 +317,14 @@ await listen('socket:message', (event) => {
 - ⚠️ Code signing for SmartScreen
 
 ### Linux
+
 - ✅ System tray (AppIndicator)
 - ✅ Desktop file autostart
 - ✅ Secret Service storage
 - ⚠️ Deep link varies by desktop environment
 
 ### Mobile (Future)
+
 - ❌ No system tray
 - ❌ Different auth flow
 - ❌ Push notifications instead of socket
@@ -312,6 +335,7 @@ await listen('socket:message', (event) => {
 ## Testing Strategy
 
 ### Unit Tests
+
 ```rust
 #[cfg(test)]
 mod tests {
@@ -324,11 +348,13 @@ mod tests {
 ```
 
 ### Integration Tests
+
 - Deep link flow end-to-end
 - Socket reconnection scenarios
 - Background persistence verification
 
 ### Manual Testing
+
 - Build debug `.app` bundle
 - Test tray behavior
 - Test window minimize/restore
@@ -339,6 +365,7 @@ mod tests {
 ## Files to Create/Modify
 
 ### New Files
+
 - `src-tauri/src/commands/mod.rs`
 - `src-tauri/src/commands/auth.rs`
 - `src-tauri/src/commands/socket.rs`
@@ -354,6 +381,7 @@ mod tests {
 - `src-tauri/src/utils/config.rs`
 
 ### Modified Files
+
 - `src-tauri/Cargo.toml` - Add dependencies
 - `src-tauri/src/lib.rs` - Refactor, use modules
 - `src-tauri/capabilities/default.json` - Add permissions
@@ -371,4 +399,4 @@ mod tests {
 
 ---
 
-*Plan created by stevenbaba - 2026-01-29*
+_Plan created by stevenbaba - 2026-01-29_
diff --git a/docs/src/01-architecture.md b/docs/src/01-architecture.md
index 005ff5953..ac849f8a9 100644
--- a/docs/src/01-architecture.md
+++ b/docs/src/01-architecture.md
@@ -3,6 +3,7 @@
 ## System Architecture
 
 The Outsourced platform is built on a layered architecture supporting:
+
 - Redux-based state management with persistence
 - Socket.io real-time communication
 - Telegram MTProto integration via service layer
@@ -14,12 +15,12 @@ The Outsourced platform is built on a layered architecture supporting:
 
 ## Entry Points
 
-| File | Purpose |
-|------|---------|
-| `main.tsx` | React root, polyfill imports, lazy deep link listener init |
-| `App.tsx` | Provider chain: Redux → PersistGate → Socket → Telegram → HashRouter |
-| `AppRoutes.tsx` | Route definitions with route guards |
-| `polyfills.ts` | Node.js polyfills (Buffer, process, util) for telegram npm package |
+| File            | Purpose                                                              |
+| --------------- | -------------------------------------------------------------------- |
+| `main.tsx`      | React root, polyfill imports, lazy deep link listener init           |
+| `App.tsx`       | Provider chain: Redux → PersistGate → Socket → Telegram → HashRouter |
+| `AppRoutes.tsx` | Route definitions with route guards                                  |
+| `polyfills.ts`  | Node.js polyfills (Buffer, process, util) for telegram npm package   |
 
 ## Provider Chain
 
@@ -36,6 +37,7 @@ Redux Provider
 ```
 
 **Why this order matters:**
+
 1. Redux must be outermost for state access
 2. PersistGate rehydrates persisted state before rendering
 3. SocketProvider depends on Redux auth token
@@ -101,6 +103,7 @@ MCP System:
 ## Data Flow
 
 ### Authentication Flow (Deep Link)
+
 1. User authenticates in browser → receives `loginToken`
 2. Browser redirects to `alphahuman://auth?token=<loginToken>`
 3. Desktop app catches deep link via Tauri plugin
@@ -110,6 +113,7 @@ MCP System:
 7. App stores session in Redux, navigates to `/onboarding` or `/home`
 
 ### Socket.io Connection Flow
+
 1. SocketProvider detects `auth.token` change
 2. Calls `socketService.connect(token)`
 3. On successful connection, initializes MCP server
@@ -117,6 +121,7 @@ MCP System:
 5. Backend can invoke tools via JSON-RPC over Socket.io
 
 ### Telegram Connection Flow
+
 1. TelegramProvider detects auth state
 2. Calls `mtprotoService.initialize(userId)` and `connect()` in parallel
 3. MTProto client authenticates with Telegram servers
@@ -126,50 +131,58 @@ MCP System:
 ## Key Patterns
 
 ### No localStorage Usage
+
 - **Rule**: Avoid `localStorage`; use Redux with persistence instead
 - **Exceptions**: Redux-persist's storage adapter (persistence layer)
 - **Telegram session**: Stored in `telegram.byUser[userId].sessionString`
 
 ### Route Guard Pattern
+
 - **PublicRoute**: Redirects authenticated users away
 - **ProtectedRoute**: Requires `token` and optionally `isOnboarded`
 - **DefaultRedirect**: Fallback based on auth state
 
 ### Settings Modal Pattern
+
 - Renders via `createPortal` when `location.pathname.startsWith('/settings')`
 - URL-based navigation without affecting main route
 - Uses `useSettingsNavigation` hook
 
 ### MCP Tool Pattern
+
 Each tool exports a handler:
+
 ```typescript
 export const toolName: TelegramMCPToolHandler = {
   call: async (args, { telegramClient, userId }) => {
     // Perform Telegram API operation
     return { success: true, data: result };
-  }
-}
+  },
+};
 ```
 
 ## File Organization
 
 ### Feature-Based Structure
+
 - `pages/` - Full-page route components
 - `pages/onboarding/` - Onboarding flow with steps
 - `components/settings/` - Settings modal system
 - `lib/mcp/telegram/tools/` - Individual MCP tools
 
 ### Slice-Based State
+
 - `store/authSlice.ts` - Authentication
 - `store/socketSlice.ts` - Socket connection
 - `store/userSlice.ts` - User profile
 - `store/telegram/` - Complex Telegram state (5 files)
 
 ### Singleton Services
+
 - `services/socketService.ts` - Socket.io
 - `services/mtprotoService.ts` - Telegram MTProto
 - `services/apiClient.ts` - HTTP REST
 
 ---
 
-*Next: [State Management](./02-state-management.md)*
+_Next: [State Management](./02-state-management.md)_
diff --git a/docs/src/05-pages-routing.md b/docs/src/05-pages-routing.md
index 16509f4ba..8c9227eed 100644
--- a/docs/src/05-pages-routing.md
+++ b/docs/src/05-pages-routing.md
@@ -58,12 +58,12 @@ Redirects authenticated users away from public pages.
 export function PublicRoute() {
   const token = useAppSelector((state) => state.auth.token);
   const isOnboarded = useAppSelector((state) =>
-    selectIsOnboarded(state, userId)
+    selectIsOnboarded(state, userId),
   );
 
   if (token) {
     // Authenticated - redirect to appropriate page
-    return <Navigate to={isOnboarded ? '/home' : '/onboarding'} replace />;
+    return <Navigate to={isOnboarded ? "/home" : "/onboarding"} replace />;
   }
 
   return <Outlet />;
@@ -82,7 +82,7 @@ interface ProtectedRouteProps {
 export function ProtectedRoute({ requireOnboarded = false }) {
   const token = useAppSelector((state) => state.auth.token);
   const isOnboarded = useAppSelector((state) =>
-    selectIsOnboarded(state, userId)
+    selectIsOnboarded(state, userId),
   );
 
   if (!token) {
@@ -105,7 +105,7 @@ Fallback route that redirects based on auth state.
 export function DefaultRedirect() {
   const token = useAppSelector((state) => state.auth.token);
   const isOnboarded = useAppSelector((state) =>
-    selectIsOnboarded(state, userId)
+    selectIsOnboarded(state, userId),
   );
 
   if (!token) {
@@ -127,6 +127,7 @@ export function DefaultRedirect() {
 Landing page for unauthenticated users.
 
 **Features:**
+
 - App introduction and branding
 - CTA to login/signup
 - Public route (redirects if authenticated)
@@ -136,6 +137,7 @@ Landing page for unauthenticated users.
 Authentication page.
 
 **Features:**
+
 - Telegram OAuth button
 - Opens `/auth/telegram?platform=desktop` in browser
 - Handles deep link callback
@@ -160,6 +162,7 @@ export function Login() {
 Main dashboard after authentication.
 
 **Features:**
+
 - Protected route (requires auth + onboarded)
 - Connection status indicators
 - Navigation to settings modal
@@ -170,14 +173,14 @@ export function Home() {
   const navigate = useNavigate();
   const user = useAppSelector((state) => state.user.profile);
   const telegramStatus = useAppSelector((state) =>
-    selectTelegramConnectionStatus(state, user?.id)
+    selectTelegramConnectionStatus(state, user?.id),
   );
 
   return (
     <div className="home-page">
       <header>
         <h1>Welcome, {user?.firstName}</h1>
-        <button onClick={() => navigate('/settings')}>Settings</button>
+        <button onClick={() => navigate("/settings")}>Settings</button>
       </header>
 
       <TelegramConnectionIndicator status={telegramStatus} />
@@ -194,6 +197,7 @@ export function Home() {
 Multi-step onboarding process.
 
 ### Structure
+
 ```
 pages/onboarding/
 ├── Onboarding.tsx           # Flow controller
@@ -209,11 +213,11 @@ pages/onboarding/
 
 ```typescript
 const STEPS = [
-  { id: 'get-started', component: GetStartedStep },
-  { id: 'privacy', component: PrivacyStep },
-  { id: 'analytics', component: AnalyticsStep },
-  { id: 'connect', component: ConnectStep },
-  { id: 'features', component: FeaturesStep }
+  { id: "get-started", component: GetStartedStep },
+  { id: "privacy", component: PrivacyStep },
+  { id: "analytics", component: AnalyticsStep },
+  { id: "connect", component: ConnectStep },
+  { id: "features", component: FeaturesStep },
 ];
 
 export function Onboarding() {
@@ -227,7 +231,7 @@ export function Onboarding() {
     } else {
       // Complete onboarding
       dispatch(setOnboarded({ userId, isOnboarded: true }));
-      navigate('/home');
+      navigate("/home");
     }
   };
 
@@ -270,7 +274,7 @@ export function ConnectStep({ onNext, onBack }: StepProps) {
         <ConnectionOption
           key={option.id}
           {...option}
-          onClick={() => option.id === 'telegram' && setShowModal(true)}
+          onClick={() => option.id === "telegram" && setShowModal(true)}
         />
       ))}
 
@@ -293,13 +297,15 @@ export function ConnectStep({ onNext, onBack }: StepProps) {
 The settings modal overlays existing content using URL-based routing.
 
 ### Modal Detection
+
 ```typescript
 // In SettingsModal.tsx
 const location = useLocation();
-const isOpen = location.pathname.startsWith('/settings');
+const isOpen = location.pathname.startsWith("/settings");
 ```
 
 ### Sub-Routes
+
 ```
 /settings              → SettingsHome (main menu)
 /settings/connections  → ConnectionsPanel
@@ -311,8 +317,9 @@ const isOpen = location.pathname.startsWith('/settings');
 ```
 
 ### Navigation
+
 ```typescript
-import { useSettingsNavigation } from './hooks/useSettingsNavigation';
+import { useSettingsNavigation } from "./hooks/useSettingsNavigation";
 
 function SettingsHome() {
   const { navigateTo, closeModal } = useSettingsNavigation();
@@ -321,7 +328,7 @@ function SettingsHome() {
     <div>
       <SettingsMenuItem
         label="Connections"
-        onClick={() => navigateTo('connections')}
+        onClick={() => navigateTo("connections")}
       />
       <button onClick={closeModal}>Close</button>
     </div>
@@ -335,13 +342,14 @@ The app uses HashRouter for desktop compatibility:
 
 ```typescript
 // App.tsx
-import { HashRouter } from 'react-router-dom';
+import { HashRouter } from "react-router-dom";
 
 // URLs look like: app://localhost/#/home
 // Instead of: app://localhost/home
 ```
 
 **Why HashRouter:**
+
 1. Tauri deep links work with hash-based URLs
 2. No server configuration needed
 3. Works with file:// protocol
@@ -353,12 +361,13 @@ Deep links are handled before routing:
 
 ```typescript
 // main.tsx
-import('./utils/desktopDeepLinkListener').then((m) => {
+import("./utils/desktopDeepLinkListener").then((m) => {
   m.setupDesktopDeepLinkListener().catch(console.error);
 });
 ```
 
 The listener intercepts `alphahuman://auth?token=...` and:
+
 1. Exchanges token via Rust command
 2. Stores session in Redux
 3. Navigates to `/onboarding` or `/home`
@@ -366,32 +375,35 @@ The listener intercepts `alphahuman://auth?token=...` and:
 ## Navigation Patterns
 
 ### Programmatic Navigation
+
 ```typescript
-import { useNavigate } from 'react-router-dom';
+import { useNavigate } from "react-router-dom";
 
 const navigate = useNavigate();
 
 // Navigate to route
-navigate('/home');
+navigate("/home");
 
 // Replace history entry
-navigate('/login', { replace: true });
+navigate("/login", { replace: true });
 
 // Go back
 navigate(-1);
 ```
 
 ### Link Component
-```typescript
-import { Link } from 'react-router-dom';
 
-<Link to="/settings">Settings</Link>
+```typescript
+import { Link } from "react-router-dom";
+
+<Link to="/settings">Settings</Link>;
 ```
 
 ### State Transfer
+
 ```typescript
 // Pass state to route
-navigate('/details', { state: { itemId: 123 } });
+navigate("/details", { state: { itemId: 123 } });
 
 // Receive state
 const location = useLocation();
@@ -400,4 +412,4 @@ const { itemId } = location.state;
 
 ---
 
-*Previous: [MCP System](./04-mcp-system.md) | Next: [Components](./06-components.md)*
+_Previous: [MCP System](./04-mcp-system.md) | Next: [Components](./06-components.md)_
diff --git a/docs/src/08-hooks-utils.md b/docs/src/08-hooks-utils.md
index 91626b377..b9721079b 100644
--- a/docs/src/08-hooks-utils.md
+++ b/docs/src/08-hooks-utils.md
@@ -24,21 +24,21 @@ function useSocket(): UseSocketReturn;
 **Usage:**
 
 ```typescript
-import { useSocket } from '../hooks/useSocket';
+import { useSocket } from "../hooks/useSocket";
 
 function ChatInput() {
   const { emit, isConnected } = useSocket();
 
   const sendMessage = (text: string) => {
     if (isConnected) {
-      emit('chat:message', { text });
+      emit("chat:message", { text });
     }
   };
 
   return (
     <input
       disabled={!isConnected}
-      onKeyDown={(e) => e.key === 'Enter' && sendMessage(e.target.value)}
+      onKeyDown={(e) => e.key === "Enter" && sendMessage(e.target.value)}
     />
   );
 }
@@ -56,8 +56,8 @@ function Notifications() {
       setNotifications((prev) => [...prev, notification]);
     };
 
-    on('notification', handler);
-    return () => off('notification', handler);
+    on("notification", handler);
+    return () => off("notification", handler);
   }, [on, off]);
 
   return <NotificationList items={notifications} />;
@@ -82,7 +82,7 @@ function useUser(): UseUserReturn;
 **Usage:**
 
 ```typescript
-import { useUser } from '../hooks/useUser';
+import { useUser } from "../hooks/useUser";
 
 function ProfileHeader() {
   const { user, loading, error, refetch } = useUser();
@@ -94,7 +94,9 @@ function ProfileHeader() {
   return (
     <div className="profile">
       <Avatar src={user.avatar} />
-      <span>{user.firstName} {user.lastName}</span>
+      <span>
+        {user.firstName} {user.lastName}
+      </span>
     </div>
   );
 }
@@ -108,10 +110,10 @@ URL-based navigation for settings modal.
 
 ```typescript
 interface UseSettingsNavigationReturn {
-  currentRoute: string;      // Current settings path
-  navigateTo: (panel: string) => void;  // Navigate to panel
-  navigateBack: () => void;  // Go back one level
-  closeModal: () => void;    // Close settings entirely
+  currentRoute: string; // Current settings path
+  navigateTo: (panel: string) => void; // Navigate to panel
+  navigateBack: () => void; // Go back one level
+  closeModal: () => void; // Close settings entirely
 }
 
 function useSettingsNavigation(): UseSettingsNavigationReturn;
@@ -120,19 +122,15 @@ function useSettingsNavigation(): UseSettingsNavigationReturn;
 **Usage:**
 
 ```typescript
-import { useSettingsNavigation } from './hooks/useSettingsNavigation';
+import { useSettingsNavigation } from "./hooks/useSettingsNavigation";
 
 function SettingsMenu() {
   const { navigateTo, closeModal } = useSettingsNavigation();
 
   return (
     <nav>
-      <button onClick={() => navigateTo('connections')}>
-        Connections
-      </button>
-      <button onClick={() => navigateTo('privacy')}>
-        Privacy
-      </button>
+      <button onClick={() => navigateTo("connections")}>Connections</button>
+      <button onClick={() => navigateTo("privacy")}>Privacy</button>
       <button onClick={closeModal}>Close</button>
     </nav>
   );
@@ -145,9 +143,9 @@ Animation state management for settings modal.
 
 ```typescript
 interface UseSettingsAnimationReturn {
-  isEntering: boolean;       // Modal is animating in
-  isExiting: boolean;        // Modal is animating out
-  animationClass: string;    // CSS class for current state
+  isEntering: boolean; // Modal is animating in
+  isExiting: boolean; // Modal is animating out
+  animationClass: string; // CSS class for current state
 }
 
 function useSettingsAnimation(): UseSettingsAnimationReturn;
@@ -156,16 +154,12 @@ function useSettingsAnimation(): UseSettingsAnimationReturn;
 **Usage:**
 
 ```typescript
-import { useSettingsAnimation } from './hooks/useSettingsAnimation';
+import { useSettingsAnimation } from "./hooks/useSettingsAnimation";
 
 function SettingsModal() {
   const { animationClass, isExiting } = useSettingsAnimation();
 
-  return (
-    <div className={`modal ${animationClass}`}>
-      {/* Content */}
-    </div>
-  );
+  return <div className={`modal ${animationClass}`}>{/* Content */}</div>;
 }
 ```
 
@@ -178,7 +172,7 @@ Environment variable access with defaults.
 ```typescript
 // Backend URL
 export const BACKEND_URL =
-  import.meta.env.VITE_BACKEND_URL || 'https://api.example.com';
+  import.meta.env.VITE_BACKEND_URL || "https://api.example.com";
 
 // Telegram configuration
 export const TELEGRAM_API_ID = import.meta.env.VITE_TELEGRAM_API_ID;
@@ -187,18 +181,18 @@ export const TELEGRAM_BOT_USERNAME = import.meta.env.VITE_TELEGRAM_BOT_USERNAME;
 export const TELEGRAM_BOT_ID = import.meta.env.VITE_TELEGRAM_BOT_ID;
 
 // Debug mode
-export const DEBUG = import.meta.env.VITE_DEBUG === 'true';
+export const DEBUG = import.meta.env.VITE_DEBUG === "true";
 ```
 
 **Usage:**
 
 ```typescript
-import { BACKEND_URL, DEBUG } from '../utils/config';
+import { BACKEND_URL, DEBUG } from "../utils/config";
 
 const response = await fetch(`${BACKEND_URL}/api/users`);
 
 if (DEBUG) {
-  console.log('Response:', response);
+  console.log("Response:", response);
 }
 ```
 
@@ -217,7 +211,7 @@ function parseDeepLink(url: string): { path: string; params: URLSearchParams };
 **Usage:**
 
 ```typescript
-import { buildAuthDeepLink } from '../utils/deeplink';
+import { buildAuthDeepLink } from "../utils/deeplink";
 
 // Build URL for browser redirect
 const deepLink = buildAuthDeepLink(loginToken);
@@ -240,12 +234,13 @@ async function setupDesktopDeepLinkListener(): Promise<void>;
 
 ```typescript
 // Lazy import to ensure Tauri IPC is ready
-import('./utils/desktopDeepLinkListener').then((m) => {
+import("./utils/desktopDeepLinkListener").then((m) => {
   m.setupDesktopDeepLinkListener().catch(console.error);
 });
 ```
 
 **What it does:**
+
 1. Listens for `onOpenUrl` events from Tauri deep-link plugin
 2. Parses `alphahuman://auth?token=...` URLs
 3. Calls Rust `exchange_token` command (bypasses CORS)
@@ -253,14 +248,15 @@ import('./utils/desktopDeepLinkListener').then((m) => {
 5. Navigates to `/onboarding` or `/home`
 
 **Loop prevention:**
+
 ```typescript
 // Set flag before navigation to prevent reprocessing
-localStorage.setItem('deepLinkHandled', 'true');
-window.location.replace('/');
+localStorage.setItem("deepLinkHandled", "true");
+window.location.replace("/");
 
 // On next load, clear flag
-if (localStorage.getItem('deepLinkHandled') === 'true') {
-  localStorage.removeItem('deepLinkHandled');
+if (localStorage.getItem("deepLinkHandled") === "true") {
+  localStorage.removeItem("deepLinkHandled");
   return; // Don't process again
 }
 ```
@@ -277,22 +273,23 @@ async function openUrl(url: string): Promise<void>;
 **Usage:**
 
 ```typescript
-import { openUrl } from '../utils/openUrl';
+import { openUrl } from "../utils/openUrl";
 
 // Opens in system browser (not in-app WebView)
-await openUrl('https://telegram.org/auth');
+await openUrl("https://telegram.org/auth");
 ```
 
 **Implementation:**
+
 ```typescript
 export async function openUrl(url: string): Promise<void> {
   try {
     // Try Tauri opener plugin first
-    const { open } = await import('@tauri-apps/plugin-opener');
+    const { open } = await import("@tauri-apps/plugin-opener");
     await open(url);
   } catch {
     // Fallback to browser API
-    window.open(url, '_blank');
+    window.open(url, "_blank");
   }
 }
 ```
@@ -305,9 +302,9 @@ The `telegram` npm package requires Node.js APIs. These are polyfilled:
 
 ```typescript
 // polyfills.ts
-import { Buffer } from 'buffer';
-import process from 'process';
-import util from 'util';
+import { Buffer } from "buffer";
+import process from "process";
+import util from "util";
 
 window.Buffer = Buffer;
 window.process = process;
@@ -318,7 +315,7 @@ window.util = util;
 
 ```typescript
 // main.tsx
-import './polyfills';
+import "./polyfills";
 // ... rest of app
 ```
 
@@ -329,15 +326,15 @@ import './polyfills';
 export default defineConfig({
   resolve: {
     alias: {
-      buffer: 'buffer',
-      process: 'process/browser',
-      util: 'util'
-    }
+      buffer: "buffer",
+      process: "process/browser",
+      util: "util",
+    },
   },
   define: {
-    'process.env': {},
-    global: 'globalThis'
-  }
+    "process.env": {},
+    global: "globalThis",
+  },
 });
 ```
 
@@ -410,10 +407,10 @@ Country list for phone number input.
 
 ```typescript
 interface Country {
-  code: string;      // "US"
-  name: string;      // "United States"
-  dialCode: string;  // "+1"
-  flag: string;      // "🇺🇸"
+  code: string; // "US"
+  name: string; // "United States"
+  dialCode: string; // "+1"
+  flag: string; // "🇺🇸"
 }
 
 export const countries: Country[];
@@ -422,7 +419,7 @@ export const countries: Country[];
 **Usage:**
 
 ```typescript
-import { countries } from '../data/countries';
+import { countries } from "../data/countries";
 
 function PhoneInput() {
   const [country, setCountry] = useState(countries[0]);
@@ -431,9 +428,9 @@ function PhoneInput() {
     <div>
       <select
         value={country.code}
-        onChange={(e) => setCountry(
-          countries.find((c) => c.code === e.target.value)
-        )}
+        onChange={(e) =>
+          setCountry(countries.find((c) => c.code === e.target.value))
+        }
       >
         {countries.map((c) => (
           <option key={c.code} value={c.code}>
@@ -456,14 +453,14 @@ Always include dependencies in useEffect:
 ```typescript
 // Good
 useEffect(() => {
-  on('event', handler);
-  return () => off('event', handler);
+  on("event", handler);
+  return () => off("event", handler);
 }, [on, off, handler]);
 
 // Bad - missing dependencies
 useEffect(() => {
-  on('event', handler);
-  return () => off('event', handler);
+  on("event", handler);
+  return () => off("event", handler);
 }, []);
 ```
 
@@ -486,7 +483,7 @@ Wrap utility calls in try-catch:
 try {
   await openUrl(url);
 } catch (error) {
-  console.error('Failed to open URL:', error);
+  console.error("Failed to open URL:", error);
   // Fallback behavior
 }
 ```
@@ -496,10 +493,10 @@ try {
 Use TypeScript generics for API calls:
 
 ```typescript
-const user = await apiClient.get<User>('/users/me');
+const user = await apiClient.get<User>("/users/me");
 // user is typed as User
 ```
 
 ---
 
-*Previous: [Providers](./07-providers.md) | [Back to Index](./README.md)*
+_Previous: [Providers](./07-providers.md) | [Back to Index](./README.md)_
diff --git a/docs/telegram-login-desktop.md b/docs/telegram-login-desktop.md
index 52a7de6f8..a8b4d48e2 100644
--- a/docs/telegram-login-desktop.md
+++ b/docs/telegram-login-desktop.md
@@ -33,7 +33,7 @@ The backend base URL is configured here (`src/utils/config.ts`):
 
 ```ts
 export const BACKEND_URL =
-  import.meta.env.VITE_BACKEND_URL || 'https://2937933edf8a.ngrok-free.app';
+  import.meta.env.VITE_BACKEND_URL || "https://2937933edf8a.ngrok-free.app";
 ```
 
 ### 2) Deep link registration (Tauri config + Rust)
@@ -77,14 +77,15 @@ pub fn run() {
 The listener is lazy-loaded in `src/main.tsx`:
 
 ```ts
-import('./utils/desktopDeepLinkListener').then(m => {
-  m.setupDesktopDeepLinkListener().catch(err => {
-    console.error('[DeepLink] setup error:', err);
+import("./utils/desktopDeepLinkListener").then((m) => {
+  m.setupDesktopDeepLinkListener().catch((err) => {
+    console.error("[DeepLink] setup error:", err);
   });
 });
 ```
 
 The deep link handler:
+
 - Accepts only the `alphahuman:` scheme
 - Requires `alphahuman://auth?token=...`
 - Calls the Rust command `exchange_token`
@@ -98,17 +99,25 @@ const handleDeepLinkUrls = async (urls: string[] | null | undefined) => {
 
   try {
     const parsed = new URL(url);
+<<<<<<< HEAD
     if (parsed.protocol !== 'alphahuman:') return;
     if (parsed.hostname !== 'auth') return;
+=======
+    if (parsed.protocol !== "outsourced:") return;
+    if (parsed.hostname !== "auth") return;
+>>>>>>> fix/telegram-mcp
 
-    const token = parsed.searchParams.get('token');
+    const token = parsed.searchParams.get("token");
     if (!token) return;
 
-    const data = await invoke('exchange_token', { backendUrl: BACKEND_URL, token });
+    const data = await invoke("exchange_token", {
+      backendUrl: BACKEND_URL,
+      token,
+    });
     // ... store sessionToken + user ...
-    window.location.hash = '/onboarding';
+    window.location.hash = "/onboarding";
   } catch (error) {
-    console.error('[DeepLink] Failed to handle deep link URL:', url, error);
+    console.error("[DeepLink] Failed to handle deep link URL:", url, error);
   }
 };
 ```
@@ -200,8 +209,7 @@ Your backend must implement **both**:
   - today it checks only `parsed.protocol === 'alphahuman:'`
   - recommended: also require `parsed.hostname === 'auth'` (and optionally a known path)
 - **Don’t skip Telegram auth in onboarding**:
-  - `src/pages/onboarding/Step1Phone.tsx` currently has a “Continue with Telegram” button that *only navigates* and does not authenticate.
+  - `src/pages/onboarding/Step1Phone.tsx` currently has a “Continue with Telegram” button that _only navigates_ and does not authenticate.
 - **Remove sensitive Telegram secrets from frontend env**:
   - any `VITE_*` variables are bundled into the frontend; don’t place bot tokens / api hashes there.
   - the desktop app typically only needs `VITE_BACKEND_URL`; Telegram verification secrets should live on the backend.
-
diff --git a/package-lock.json b/package-lock.json
index f38f2af36..1aed6fed3 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -38,12 +38,14 @@
         "@types/react-dom": "^19.1.6",
         "@types/redux-logger": "^3.0.13",
         "@vitejs/plugin-react": "^4.6.0",
+        "@vitest/coverage-v8": "^4.0.18",
         "autoprefixer": "^10.4.23",
         "postcss": "^8.5.6",
         "tailwindcss": "^3.4.19",
         "typescript": "~5.8.3",
         "vite": "^7.0.4",
-        "vite-plugin-node-polyfills": "^0.25.0"
+        "vite-plugin-node-polyfills": "^0.25.0",
+        "vitest": "^4.0.18"
       }
     },
     "node_modules/@alloc/quick-lru": {
@@ -341,6 +343,16 @@
         "node": ">=6.9.0"
       }
     },
+    "node_modules/@bcoe/v8-coverage": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/@bcoe/v8-coverage/-/v8-coverage-1.0.2.tgz",
+      "integrity": "sha512-6zABk/ECA/QYSCQ1NGiVwwbQerUCZ+TQbp64Q3AgmfNvurHH0j8TtXa1qbShXA6qqkpAj4V5W8pP6mLe1mcMqA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/@cryptography/aes": {
       "version": "0.1.1",
       "resolved": "https://registry.npmjs.org/@cryptography/aes/-/aes-0.1.1.tgz",
@@ -1640,6 +1652,24 @@
         "@babel/types": "^7.28.2"
       }
     },
+    "node_modules/@types/chai": {
+      "version": "5.2.3",
+      "resolved": "https://registry.npmjs.org/@types/chai/-/chai-5.2.3.tgz",
+      "integrity": "sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/deep-eql": "*",
+        "assertion-error": "^2.0.1"
+      }
+    },
+    "node_modules/@types/deep-eql": {
+      "version": "4.0.2",
+      "resolved": "https://registry.npmjs.org/@types/deep-eql/-/deep-eql-4.0.2.tgz",
+      "integrity": "sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/estree": {
       "version": "1.0.8",
       "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.8.tgz",
@@ -1740,6 +1770,158 @@
         "vite": "^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0"
       }
     },
+    "node_modules/@vitest/coverage-v8": {
+      "version": "4.0.18",
+      "resolved": "https://registry.npmjs.org/@vitest/coverage-v8/-/coverage-v8-4.0.18.tgz",
+      "integrity": "sha512-7i+N2i0+ME+2JFZhfuz7Tg/FqKtilHjGyGvoHYQ6iLV0zahbsJ9sljC9OcFcPDbhYKCet+sG8SsVqlyGvPflZg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@bcoe/v8-coverage": "^1.0.2",
+        "@vitest/utils": "4.0.18",
+        "ast-v8-to-istanbul": "^0.3.10",
+        "istanbul-lib-coverage": "^3.2.2",
+        "istanbul-lib-report": "^3.0.1",
+        "istanbul-reports": "^3.2.0",
+        "magicast": "^0.5.1",
+        "obug": "^2.1.1",
+        "std-env": "^3.10.0",
+        "tinyrainbow": "^3.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "@vitest/browser": "4.0.18",
+        "vitest": "4.0.18"
+      },
+      "peerDependenciesMeta": {
+        "@vitest/browser": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@vitest/expect": {
+      "version": "4.0.18",
+      "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-4.0.18.tgz",
+      "integrity": "sha512-8sCWUyckXXYvx4opfzVY03EOiYVxyNrHS5QxX3DAIi5dpJAAkyJezHCP77VMX4HKA2LDT/Jpfo8i2r5BE3GnQQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@standard-schema/spec": "^1.0.0",
+        "@types/chai": "^5.2.2",
+        "@vitest/spy": "4.0.18",
+        "@vitest/utils": "4.0.18",
+        "chai": "^6.2.1",
+        "tinyrainbow": "^3.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/mocker": {
+      "version": "4.0.18",
+      "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-4.0.18.tgz",
+      "integrity": "sha512-HhVd0MDnzzsgevnOWCBj5Otnzobjy5wLBe4EdeeFGv8luMsGcYqDuFRMcttKWZA5vVO8RFjexVovXvAM4JoJDQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/spy": "4.0.18",
+        "estree-walker": "^3.0.3",
+        "magic-string": "^0.30.21"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "msw": "^2.4.9",
+        "vite": "^6.0.0 || ^7.0.0-0"
+      },
+      "peerDependenciesMeta": {
+        "msw": {
+          "optional": true
+        },
+        "vite": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@vitest/mocker/node_modules/estree-walker": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-3.0.3.tgz",
+      "integrity": "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.0"
+      }
+    },
+    "node_modules/@vitest/pretty-format": {
+      "version": "4.0.18",
+      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-4.0.18.tgz",
+      "integrity": "sha512-P24GK3GulZWC5tz87ux0m8OADrQIUVDPIjjj65vBXYG17ZeU3qD7r+MNZ1RNv4l8CGU2vtTRqixrOi9fYk/yKw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tinyrainbow": "^3.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/runner": {
+      "version": "4.0.18",
+      "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-4.0.18.tgz",
+      "integrity": "sha512-rpk9y12PGa22Jg6g5M3UVVnTS7+zycIGk9ZNGN+m6tZHKQb7jrP7/77WfZy13Y/EUDd52NDsLRQhYKtv7XfPQw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/utils": "4.0.18",
+        "pathe": "^2.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/snapshot": {
+      "version": "4.0.18",
+      "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-4.0.18.tgz",
+      "integrity": "sha512-PCiV0rcl7jKQjbgYqjtakly6T1uwv/5BQ9SwBLekVg/EaYeQFPiXcgrC2Y7vDMA8dM1SUEAEV82kgSQIlXNMvA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/pretty-format": "4.0.18",
+        "magic-string": "^0.30.21",
+        "pathe": "^2.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/spy": {
+      "version": "4.0.18",
+      "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-4.0.18.tgz",
+      "integrity": "sha512-cbQt3PTSD7P2OARdVW3qWER5EGq7PHlvE+QfzSC0lbwO+xnt7+XH06ZzFjFRgzUX//JmpxrCu92VdwvEPlWSNw==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/utils": {
+      "version": "4.0.18",
+      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-4.0.18.tgz",
+      "integrity": "sha512-msMRKLMVLWygpK3u2Hybgi4MNjcYJvwTb0Ru09+fOyCXIgT5raYP041DRRdiJiI3k/2U6SEbAETB3YtBrUkCFA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/pretty-format": "4.0.18",
+        "tinyrainbow": "^3.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
     "node_modules/any-promise": {
       "version": "1.3.0",
       "resolved": "https://registry.npmjs.org/any-promise/-/any-promise-1.3.0.tgz",
@@ -1814,6 +1996,45 @@
         "util": "^0.12.5"
       }
     },
+    "node_modules/assertion-error": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-2.0.1.tgz",
+      "integrity": "sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/ast-v8-to-istanbul": {
+      "version": "0.3.10",
+      "resolved": "https://registry.npmjs.org/ast-v8-to-istanbul/-/ast-v8-to-istanbul-0.3.10.tgz",
+      "integrity": "sha512-p4K7vMz2ZSk3wN8l5o3y2bJAoZXT3VuJI5OLTATY/01CYWumWvwkUw0SqDBnNq6IiTO3qDa1eSQDibAV8g7XOQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/trace-mapping": "^0.3.31",
+        "estree-walker": "^3.0.3",
+        "js-tokens": "^9.0.1"
+      }
+    },
+    "node_modules/ast-v8-to-istanbul/node_modules/estree-walker": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-3.0.3.tgz",
+      "integrity": "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.0"
+      }
+    },
+    "node_modules/ast-v8-to-istanbul/node_modules/js-tokens": {
+      "version": "9.0.1",
+      "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-9.0.1.tgz",
+      "integrity": "sha512-mxa9E9ITFOt0ban3j6L5MpjwegGz6lBQmM1IJkWeBZGcMxto50+eWdjC/52xDbS2vy0k7vIMK0Fe2wfL9OQSpQ==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/async-mutex": {
       "version": "0.3.2",
       "resolved": "https://registry.npmjs.org/async-mutex/-/async-mutex-0.3.2.tgz",
@@ -2267,6 +2488,16 @@
       ],
       "license": "CC-BY-4.0"
     },
+    "node_modules/chai": {
+      "version": "6.2.2",
+      "resolved": "https://registry.npmjs.org/chai/-/chai-6.2.2.tgz",
+      "integrity": "sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/chokidar": {
       "version": "3.6.0",
       "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-3.6.0.tgz",
@@ -2747,6 +2978,13 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/es-module-lexer": {
+      "version": "1.7.0",
+      "resolved": "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-1.7.0.tgz",
+      "integrity": "sha512-jEQoCwk8hyb2AZziIOLhDqpm5+2ww5uIE6lkO/6jcOCusfk6LhMHpXXfBLXTZ7Ydyt0j4VoUQv6uGNYbdW+kBA==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/es-object-atoms": {
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/es-object-atoms/-/es-object-atoms-1.1.1.tgz",
@@ -2904,6 +3142,16 @@
         "safe-buffer": "^5.1.1"
       }
     },
+    "node_modules/expect-type": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/expect-type/-/expect-type-1.3.0.tgz",
+      "integrity": "sha512-knvyeauYhqjOYvQ66MznSMs83wmHrCycNEN6Ao+2AeYEfxUIkuiVxdEa1qlGEPK+We3n0THiDciYSsCcgW/DoA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=12.0.0"
+      }
+    },
     "node_modules/ext": {
       "version": "1.7.0",
       "resolved": "https://registry.npmjs.org/ext/-/ext-1.7.0.tgz",
@@ -3141,6 +3389,16 @@
       "integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==",
       "license": "ISC"
     },
+    "node_modules/has-flag": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz",
+      "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/has-property-descriptors": {
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/has-property-descriptors/-/has-property-descriptors-1.0.2.tgz",
@@ -3229,6 +3487,13 @@
         "minimalistic-crypto-utils": "^1.0.1"
       }
     },
+    "node_modules/html-escaper": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/html-escaper/-/html-escaper-2.0.2.tgz",
+      "integrity": "sha512-H2iMtd0I4Mt5eYiapRdIDjp+XzelXQ0tFE4JS7YFwFevXXMmOp9myNrUvCg0D6ws8iqkRPBfKHgbwig1SmlLfg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/htmlparser2": {
       "version": "6.1.0",
       "resolved": "https://registry.npmjs.org/htmlparser2/-/htmlparser2-6.1.0.tgz",
@@ -3491,6 +3756,45 @@
         "node": ">=10"
       }
     },
+    "node_modules/istanbul-lib-coverage": {
+      "version": "3.2.2",
+      "resolved": "https://registry.npmjs.org/istanbul-lib-coverage/-/istanbul-lib-coverage-3.2.2.tgz",
+      "integrity": "sha512-O8dpsF+r0WV/8MNRKfnmrtCWhuKjxrq2w+jpzBL5UZKTi2LeVWnWOmWRxFlesJONmc+wLAGvKQZEOanko0LFTg==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/istanbul-lib-report": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/istanbul-lib-report/-/istanbul-lib-report-3.0.1.tgz",
+      "integrity": "sha512-GCfE1mtsHGOELCU8e/Z7YWzpmybrx/+dSTfLrvY8qRmaY6zXTKWn6WQIjaAFw069icm6GVMNkgu0NzI4iPZUNw==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "istanbul-lib-coverage": "^3.0.0",
+        "make-dir": "^4.0.0",
+        "supports-color": "^7.1.0"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/istanbul-reports": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/istanbul-reports/-/istanbul-reports-3.2.0.tgz",
+      "integrity": "sha512-HGYWWS/ehqTV3xN10i23tkPkpH46MLCIMFNCaaKNavAXTF1RkqxawEPtnjnGZ6XKSInBKkiOA5BKS+aZiY3AvA==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "html-escaper": "^2.0.0",
+        "istanbul-lib-report": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/js-tokens": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz",
@@ -3599,6 +3903,47 @@
         "@jridgewell/sourcemap-codec": "^1.5.5"
       }
     },
+    "node_modules/magicast": {
+      "version": "0.5.1",
+      "resolved": "https://registry.npmjs.org/magicast/-/magicast-0.5.1.tgz",
+      "integrity": "sha512-xrHS24IxaLrvuo613F719wvOIv9xPHFWQHuvGUBmPnCA/3MQxKI3b+r7n1jAoDHmsbC5bRhTZYR77invLAxVnw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/parser": "^7.28.5",
+        "@babel/types": "^7.28.5",
+        "source-map-js": "^1.2.1"
+      }
+    },
+    "node_modules/make-dir": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/make-dir/-/make-dir-4.0.0.tgz",
+      "integrity": "sha512-hXdUTZYIVOt1Ex//jAQi+wTZZpUpwBj/0QsOzqegb3rGMMeJiSEu5xLHnYfBrRV4RH2+OCSOO95Is/7x1WJ4bw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "semver": "^7.5.3"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/make-dir/node_modules/semver": {
+      "version": "7.7.3",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.3.tgz",
+      "integrity": "sha512-SdsKMrI9TdgjdweUSR9MweHA4EJ8YxHn8DFaDisvhVlUOe4BF1tLD7GAj0lIqWVl+dPb/rExr0Btby5loQm20Q==",
+      "dev": true,
+      "license": "ISC",
+      "bin": {
+        "semver": "bin/semver.js"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
     "node_modules/math-intrinsics": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz",
@@ -3942,6 +4287,17 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/obug": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/obug/-/obug-2.1.1.tgz",
+      "integrity": "sha512-uTqF9MuPraAQ+IsnPf366RG4cP9RtUi7MLO1N3KEc+wb0a6yKpeL0lmk2IB1jY5KHPAlTc6T/JRdC/YqxHNwkQ==",
+      "dev": true,
+      "funding": [
+        "https://github.com/sponsors/sxzz",
+        "https://opencollective.com/debug"
+      ],
+      "license": "MIT"
+    },
     "node_modules/os-browserify": {
       "version": "0.3.0",
       "resolved": "https://registry.npmjs.org/os-browserify/-/os-browserify-0.3.0.tgz",
@@ -4026,6 +4382,13 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/pathe": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/pathe/-/pathe-2.0.3.tgz",
+      "integrity": "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/pbkdf2": {
       "version": "3.1.5",
       "resolved": "https://registry.npmjs.org/pbkdf2/-/pbkdf2-3.1.5.tgz",
@@ -4951,6 +5314,13 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/siginfo": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/siginfo/-/siginfo-2.0.0.tgz",
+      "integrity": "sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==",
+      "dev": true,
+      "license": "ISC"
+    },
     "node_modules/slide": {
       "version": "1.1.6",
       "resolved": "https://registry.npmjs.org/slide/-/slide-1.1.6.tgz",
@@ -5022,6 +5392,20 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/stackback": {
+      "version": "0.0.2",
+      "resolved": "https://registry.npmjs.org/stackback/-/stackback-0.0.2.tgz",
+      "integrity": "sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/std-env": {
+      "version": "3.10.0",
+      "resolved": "https://registry.npmjs.org/std-env/-/std-env-3.10.0.tgz",
+      "integrity": "sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/store2": {
       "version": "2.14.4",
       "resolved": "https://registry.npmjs.org/store2/-/store2-2.14.4.tgz",
@@ -5085,6 +5469,19 @@
         "node": ">=16 || 14 >=14.17"
       }
     },
+    "node_modules/supports-color": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz",
+      "integrity": "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "has-flag": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/supports-preserve-symlinks-flag": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/supports-preserve-symlinks-flag/-/supports-preserve-symlinks-flag-1.0.0.tgz",
@@ -5222,6 +5619,23 @@
         "node": ">=0.6.0"
       }
     },
+    "node_modules/tinybench": {
+      "version": "2.9.0",
+      "resolved": "https://registry.npmjs.org/tinybench/-/tinybench-2.9.0.tgz",
+      "integrity": "sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/tinyexec": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-1.0.2.tgz",
+      "integrity": "sha512-W/KYk+NFhkmsYpuHq5JykngiOCnxeVL8v8dFnqxSD8qEEdRfXk1SDM6JzNqcERbcGYj9tMrDQBYV9cjgnunFIg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/tinyglobby": {
       "version": "0.2.15",
       "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.15.tgz",
@@ -5239,6 +5653,16 @@
         "url": "https://github.com/sponsors/SuperchupuDev"
       }
     },
+    "node_modules/tinyrainbow": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/tinyrainbow/-/tinyrainbow-3.0.3.tgz",
+      "integrity": "sha512-PSkbLUoxOFRzJYjjxHJt9xro7D+iilgMX/C9lawzVuYiIdcihh9DXmVibBe8lmcFrRi/VzlPjBxbN7rH24q8/Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
     "node_modules/to-buffer": {
       "version": "1.2.2",
       "resolved": "https://registry.npmjs.org/to-buffer/-/to-buffer-1.2.2.tgz",
@@ -5526,6 +5950,84 @@
         "vite": "^2.0.0 || ^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0"
       }
     },
+    "node_modules/vitest": {
+      "version": "4.0.18",
+      "resolved": "https://registry.npmjs.org/vitest/-/vitest-4.0.18.tgz",
+      "integrity": "sha512-hOQuK7h0FGKgBAas7v0mSAsnvrIgAvWmRFjmzpJ7SwFHH3g1k2u37JtYwOwmEKhK6ZO3v9ggDBBm0La1LCK4uQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/expect": "4.0.18",
+        "@vitest/mocker": "4.0.18",
+        "@vitest/pretty-format": "4.0.18",
+        "@vitest/runner": "4.0.18",
+        "@vitest/snapshot": "4.0.18",
+        "@vitest/spy": "4.0.18",
+        "@vitest/utils": "4.0.18",
+        "es-module-lexer": "^1.7.0",
+        "expect-type": "^1.2.2",
+        "magic-string": "^0.30.21",
+        "obug": "^2.1.1",
+        "pathe": "^2.0.3",
+        "picomatch": "^4.0.3",
+        "std-env": "^3.10.0",
+        "tinybench": "^2.9.0",
+        "tinyexec": "^1.0.2",
+        "tinyglobby": "^0.2.15",
+        "tinyrainbow": "^3.0.3",
+        "vite": "^6.0.0 || ^7.0.0",
+        "why-is-node-running": "^2.3.0"
+      },
+      "bin": {
+        "vitest": "vitest.mjs"
+      },
+      "engines": {
+        "node": "^20.0.0 || ^22.0.0 || >=24.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "@edge-runtime/vm": "*",
+        "@opentelemetry/api": "^1.9.0",
+        "@types/node": "^20.0.0 || ^22.0.0 || >=24.0.0",
+        "@vitest/browser-playwright": "4.0.18",
+        "@vitest/browser-preview": "4.0.18",
+        "@vitest/browser-webdriverio": "4.0.18",
+        "@vitest/ui": "4.0.18",
+        "happy-dom": "*",
+        "jsdom": "*"
+      },
+      "peerDependenciesMeta": {
+        "@edge-runtime/vm": {
+          "optional": true
+        },
+        "@opentelemetry/api": {
+          "optional": true
+        },
+        "@types/node": {
+          "optional": true
+        },
+        "@vitest/browser-playwright": {
+          "optional": true
+        },
+        "@vitest/browser-preview": {
+          "optional": true
+        },
+        "@vitest/browser-webdriverio": {
+          "optional": true
+        },
+        "@vitest/ui": {
+          "optional": true
+        },
+        "happy-dom": {
+          "optional": true
+        },
+        "jsdom": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/vm-browserify": {
       "version": "1.1.2",
       "resolved": "https://registry.npmjs.org/vm-browserify/-/vm-browserify-1.1.2.tgz",
@@ -5586,6 +6088,23 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/why-is-node-running": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/why-is-node-running/-/why-is-node-running-2.3.0.tgz",
+      "integrity": "sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "siginfo": "^2.0.0",
+        "stackback": "0.0.2"
+      },
+      "bin": {
+        "why-is-node-running": "cli.js"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/write-file-atomic": {
       "version": "1.3.4",
       "resolved": "https://registry.npmjs.org/write-file-atomic/-/write-file-atomic-1.3.4.tgz",
diff --git a/package.json b/package.json
index 0ec11b6c1..4d0d5a955 100644
--- a/package.json
+++ b/package.json
@@ -10,7 +10,10 @@
     "tauri": "tauri",
     "macos:build": "tauri build --debug --bundles app",
     "macos:run": "open 'src-tauri/target/debug/bundle/macos/AlphaHuman.app'",
-    "macos:dev": "tauri build --debug --bundles app && open 'src-tauri/target/debug/bundle/macos/AlphaHuman.app'"
+    "macos:dev": "tauri build --debug --bundles app && open 'src-tauri/target/debug/bundle/macos/AlphaHuman.app'",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
     "@reduxjs/toolkit": "^2.11.2",
@@ -43,11 +46,13 @@
     "@types/react-dom": "^19.1.6",
     "@types/redux-logger": "^3.0.13",
     "@vitejs/plugin-react": "^4.6.0",
+    "@vitest/coverage-v8": "^4.0.18",
     "autoprefixer": "^10.4.23",
     "postcss": "^8.5.6",
     "tailwindcss": "^3.4.19",
     "typescript": "~5.8.3",
     "vite": "^7.0.4",
-    "vite-plugin-node-polyfills": "^0.25.0"
+    "vite-plugin-node-polyfills": "^0.25.0",
+    "vitest": "^4.0.18"
   }
 }
diff --git a/src-tauri/gen/apple/project.yml b/src-tauri/gen/apple/project.yml
index acad0d188..329421f2f 100644
--- a/src-tauri/gen/apple/project.yml
+++ b/src-tauri/gen/apple/project.yml
@@ -1,6 +1,6 @@
 name: tauri-app
 options:
-  bundleIdPrefix: com.megamind.tauri-app
+  bundleIdPrefix: com.alphahuman.app
   deploymentTarget:
     iOS: 14.0
 fileGroups: [../../src]
@@ -11,7 +11,7 @@ settingGroups:
   app:
     base:
       PRODUCT_NAME: tauri-app
-      PRODUCT_BUNDLE_IDENTIFIER: com.megamind.tauri-app
+      PRODUCT_BUNDLE_IDENTIFIER: com.alphahuman.app
 targetTemplates:
   app:
     type: application
@@ -63,7 +63,7 @@ targets:
       base:
         ENABLE_BITCODE: false
         ARCHS: [arm64]
-        VALID_ARCHS: arm64 
+        VALID_ARCHS: arm64
         LIBRARY_SEARCH_PATHS[arch=x86_64]: $(inherited) $(PROJECT_DIR)/Externals/x86_64/$(CONFIGURATION) $(SDKROOT)/usr/lib/swift $(TOOLCHAIN_DIR)/usr/lib/swift/$(PLATFORM_NAME) $(TOOLCHAIN_DIR)/usr/lib/swift-5.0/$(PLATFORM_NAME)
         LIBRARY_SEARCH_PATHS[arch=arm64]: $(inherited) $(PROJECT_DIR)/Externals/arm64/$(CONFIGURATION) $(SDKROOT)/usr/lib/swift $(TOOLCHAIN_DIR)/usr/lib/swift/$(PLATFORM_NAME) $(TOOLCHAIN_DIR)/usr/lib/swift-5.0/$(PLATFORM_NAME)
         ALWAYS_EMBED_SWIFT_STANDARD_LIBRARIES: true
@@ -85,4 +85,4 @@ targets:
         basedOnDependencyAnalysis: false
         outputFiles:
           - $(SRCROOT)/Externals/x86_64/${CONFIGURATION}/libapp.a
-          - $(SRCROOT)/Externals/arm64/${CONFIGURATION}/libapp.a
\ No newline at end of file
+          - $(SRCROOT)/Externals/arm64/${CONFIGURATION}/libapp.a
diff --git a/src-tauri/gen/apple/tauri-app.xcodeproj/project.pbxproj b/src-tauri/gen/apple/tauri-app.xcodeproj/project.pbxproj
index 68fd3a099..3a7e3b4d0 100644
--- a/src-tauri/gen/apple/tauri-app.xcodeproj/project.pbxproj
+++ b/src-tauri/gen/apple/tauri-app.xcodeproj/project.pbxproj
@@ -273,7 +273,7 @@
 				);
 				"LIBRARY_SEARCH_PATHS[arch=arm64]" = "$(inherited) $(PROJECT_DIR)/Externals/arm64/$(CONFIGURATION) $(SDKROOT)/usr/lib/swift $(TOOLCHAIN_DIR)/usr/lib/swift/$(PLATFORM_NAME) $(TOOLCHAIN_DIR)/usr/lib/swift-5.0/$(PLATFORM_NAME)";
 				"LIBRARY_SEARCH_PATHS[arch=x86_64]" = "$(inherited) $(PROJECT_DIR)/Externals/x86_64/$(CONFIGURATION) $(SDKROOT)/usr/lib/swift $(TOOLCHAIN_DIR)/usr/lib/swift/$(PLATFORM_NAME) $(TOOLCHAIN_DIR)/usr/lib/swift-5.0/$(PLATFORM_NAME)";
-				PRODUCT_BUNDLE_IDENTIFIER = "com.megamind.tauri-app";
+				PRODUCT_BUNDLE_IDENTIFIER = "com.alphahuman.app";
 				PRODUCT_NAME = "tauri-app";
 				SDKROOT = iphoneos;
 				TARGETED_DEVICE_FAMILY = "1,2";
@@ -423,7 +423,7 @@
 				);
 				"LIBRARY_SEARCH_PATHS[arch=arm64]" = "$(inherited) $(PROJECT_DIR)/Externals/arm64/$(CONFIGURATION) $(SDKROOT)/usr/lib/swift $(TOOLCHAIN_DIR)/usr/lib/swift/$(PLATFORM_NAME) $(TOOLCHAIN_DIR)/usr/lib/swift-5.0/$(PLATFORM_NAME)";
 				"LIBRARY_SEARCH_PATHS[arch=x86_64]" = "$(inherited) $(PROJECT_DIR)/Externals/x86_64/$(CONFIGURATION) $(SDKROOT)/usr/lib/swift $(TOOLCHAIN_DIR)/usr/lib/swift/$(PLATFORM_NAME) $(TOOLCHAIN_DIR)/usr/lib/swift-5.0/$(PLATFORM_NAME)";
-				PRODUCT_BUNDLE_IDENTIFIER = "com.megamind.tauri-app";
+				PRODUCT_BUNDLE_IDENTIFIER = "com.alphahuman.app";
 				PRODUCT_NAME = "tauri-app";
 				SDKROOT = iphoneos;
 				TARGETED_DEVICE_FAMILY = "1,2";
diff --git a/src-tauri/src/utils/config.rs b/src-tauri/src/utils/config.rs
index 7a5baeafa..03245c6c6 100644
--- a/src-tauri/src/utils/config.rs
+++ b/src-tauri/src/utils/config.rs
@@ -6,10 +6,10 @@
 use std::env;
 
 /// Default backend URL (can be overridden via BACKEND_URL env var)
-pub const DEFAULT_BACKEND_URL: &str = "https://api.alphahuman.io";
+pub const DEFAULT_BACKEND_URL: &str = "https://api.alphahuman.xyz";
 
 /// Application identifier for keychain storage
-pub const APP_IDENTIFIER: &str = "com.megamind.tauri-app";
+pub const APP_IDENTIFIER: &str = "com.alphahuman.app";
 
 /// Service name for keychain
 pub const KEYCHAIN_SERVICE: &str = "AlphaHuman";
@@ -17,11 +17,6 @@ pub const KEYCHAIN_SERVICE: &str = "AlphaHuman";
 /// Deep link scheme
 pub const DEEP_LINK_SCHEME: &str = "alphahuman";
 
-/// Socket.io reconnection settings
-pub const SOCKET_RECONNECT_ATTEMPTS: u32 = 5;
-pub const SOCKET_RECONNECT_DELAY_MS: u64 = 1000;
-pub const SOCKET_PING_INTERVAL_MS: u64 = 25000;
-
 /// Get the backend URL from environment or use default
 pub fn get_backend_url() -> String {
     env::var("BACKEND_URL").unwrap_or_else(|_| DEFAULT_BACKEND_URL.to_string())
@@ -31,8 +26,3 @@ pub fn get_backend_url() -> String {
 pub fn get_telegram_widget_url() -> String {
     format!("{}/auth/telegram-widget?redirect={}://auth", get_backend_url(), DEEP_LINK_SCHEME)
 }
-
-/// Get the token exchange endpoint URL
-pub fn get_token_exchange_url() -> String {
-    format!("{}/auth/desktop-exchange", get_backend_url())
-}
diff --git a/src-tauri/tauri.conf.json b/src-tauri/tauri.conf.json
index bb7a40919..77f5f42de 100644
--- a/src-tauri/tauri.conf.json
+++ b/src-tauri/tauri.conf.json
@@ -2,7 +2,7 @@
   "$schema": "https://schema.tauri.app/config/2",
   "productName": "AlphaHuman",
   "version": "0.1.0",
-  "identifier": "com.megamind.tauri-app",
+  "identifier": "com.alphahuman.app",
   "build": {
     "beforeDevCommand": "npm run dev",
     "devUrl": "http://localhost:1420",
diff --git a/src/__tests__/fixtures/mcpContext.ts b/src/__tests__/fixtures/mcpContext.ts
new file mode 100644
index 000000000..ef0a949a0
--- /dev/null
+++ b/src/__tests__/fixtures/mcpContext.ts
@@ -0,0 +1,27 @@
+/**
+ * Factory builder for TelegramMCPContext (used by tool handlers).
+ */
+
+import { vi } from 'vitest';
+import type { TelegramMCPContext } from "../../lib/mcp/telegram/types";
+import type { TelegramState } from "../../store/telegram/types";
+import { initialState } from "../../store/telegram/types";
+
+function createMockTransport() {
+  return {
+    emit: vi.fn(),
+    on: vi.fn(),
+    off: vi.fn(),
+    updateSocket: vi.fn(),
+    connected: true,
+  } as unknown as TelegramMCPContext["transport"];
+}
+
+export function createMockContext(
+  telegramOverrides: Partial<TelegramState> = {},
+): TelegramMCPContext {
+  return {
+    telegramState: { ...initialState, ...telegramOverrides },
+    transport: createMockTransport(),
+  };
+}
diff --git a/src/__tests__/fixtures/rootState.ts b/src/__tests__/fixtures/rootState.ts
new file mode 100644
index 000000000..b6c598d4b
--- /dev/null
+++ b/src/__tests__/fixtures/rootState.ts
@@ -0,0 +1,66 @@
+/**
+ * Factory builder for a mock RootState matching the Redux store shape.
+ */
+
+import type { TelegramState } from "../../store/telegram/types";
+import { initialState as telegramInitialState } from "../../store/telegram/types";
+
+/**
+ * Minimal RootState shape matching the real store (without persist wrappers).
+ * Only includes the fields tests actually need.
+ */
+export interface MockRootState {
+  auth: {
+    token: string | null;
+    isOnboardedByUser: Record<string, boolean>;
+  };
+  socket: {
+    byUser: Record<
+      string,
+      { status: "connected" | "disconnected" | "connecting"; socketId: string | null }
+    >;
+  };
+  user: {
+    user: { _id: string; telegramId: number; [key: string]: unknown } | null;
+    isLoading: boolean;
+    error: string | null;
+  };
+  telegram: {
+    byUser: Record<string, TelegramState>;
+  };
+}
+
+const DEFAULT_USER_ID = "user_123";
+
+export function createMockRootState(
+  telegramOverrides: Partial<TelegramState> = {},
+  userId = DEFAULT_USER_ID,
+): MockRootState {
+  return {
+    auth: {
+      token: "mock-jwt-token",
+      isOnboardedByUser: { [userId]: true },
+    },
+    socket: {
+      byUser: {
+        [userId]: { status: "connected", socketId: "sock_1" },
+      },
+    },
+    user: {
+      user: {
+        _id: userId,
+        telegramId: 12345,
+      },
+      isLoading: false,
+      error: null,
+    },
+    telegram: {
+      byUser: {
+        [userId]: {
+          ...telegramInitialState,
+          ...telegramOverrides,
+        },
+      },
+    },
+  };
+}
diff --git a/src/__tests__/fixtures/telegramState.ts b/src/__tests__/fixtures/telegramState.ts
new file mode 100644
index 000000000..a544e1ede
--- /dev/null
+++ b/src/__tests__/fixtures/telegramState.ts
@@ -0,0 +1,66 @@
+/**
+ * Factory builders for Telegram entity fixtures.
+ */
+
+import type {
+  TelegramUser,
+  TelegramChat,
+  TelegramMessage,
+  TelegramState,
+} from "../../store/telegram/types";
+import { initialState } from "../../store/telegram/types";
+
+let idCounter = 1000;
+
+export function createTelegramUser(
+  overrides: Partial<TelegramUser> = {},
+): TelegramUser {
+  const id = String(idCounter++);
+  return {
+    id,
+    firstName: "Test",
+    lastName: "User",
+    username: `user_${id}`,
+    isBot: false,
+    ...overrides,
+  };
+}
+
+export function createTelegramChat(
+  overrides: Partial<TelegramChat> = {},
+): TelegramChat {
+  const id = String(idCounter++);
+  return {
+    id,
+    title: `Chat ${id}`,
+    type: "private",
+    unreadCount: 0,
+    isPinned: false,
+    ...overrides,
+  };
+}
+
+export function createTelegramMessage(
+  overrides: Partial<TelegramMessage> = {},
+): TelegramMessage {
+  const id = String(idCounter++);
+  return {
+    id,
+    chatId: "1",
+    date: Math.floor(Date.now() / 1000),
+    message: `Message ${id}`,
+    isOutgoing: false,
+    isEdited: false,
+    isForwarded: false,
+    ...overrides,
+  };
+}
+
+export function createTelegramState(
+  overrides: Partial<TelegramState> = {},
+): TelegramState {
+  return {
+    ...initialState,
+    ...overrides,
+  };
+}
diff --git a/src/__tests__/setup.ts b/src/__tests__/setup.ts
new file mode 100644
index 000000000..6bcfb733e
--- /dev/null
+++ b/src/__tests__/setup.ts
@@ -0,0 +1,29 @@
+/**
+ * Global test setup — runs before every test file.
+ *
+ * - Silences console output during tests (unless DEBUG_TESTS=1)
+ * - Resets rate limiter module-level state between tests
+ */
+
+import { beforeEach, vi } from "vitest";
+
+// Silence console during tests to keep output clean
+if (!process.env.DEBUG_TESTS) {
+  vi.spyOn(console, "log").mockImplementation(() => {});
+  vi.spyOn(console, "warn").mockImplementation(() => {});
+  vi.spyOn(console, "error").mockImplementation(() => {});
+}
+
+// Reset rate limiter per-request counter before each test.
+// The module keeps mutable state (callHistory, lastCallTime, callsInCurrentRequest)
+// that leaks between tests if not cleared.
+beforeEach(async () => {
+  try {
+    const { resetRequestCallCount } = await import("../lib/mcp/rateLimiter");
+    if (typeof resetRequestCallCount === "function") {
+      resetRequestCallCount();
+    }
+  } catch {
+    // Module may be fully mocked in some test files — safe to skip
+  }
+});
diff --git a/src/components/TelegramLoginButton.tsx b/src/components/TelegramLoginButton.tsx
index 867652f15..d4c326a78 100644
--- a/src/components/TelegramLoginButton.tsx
+++ b/src/components/TelegramLoginButton.tsx
@@ -21,9 +21,8 @@ const TelegramLoginButton = ({
 
     // Desktop (Tauri): use system browser → backend Telegram widget → deep link back to app.
     if (isTauri()) await openUrl(`https://t.me/${TELEGRAM_BOT_USERNAME}?start=login_desktop`);
-
     // Web fallback: open bot (existing flow).
-    await openUrl(`https://t.me/${TELEGRAM_BOT_USERNAME}?start=login`);
+    else await openUrl(`https://t.me/${TELEGRAM_BOT_USERNAME}?start=login`);
   };
 
   const isDisabled = externalDisabled;
diff --git a/src/lib/mcp/errorHandler.test.ts b/src/lib/mcp/errorHandler.test.ts
new file mode 100644
index 000000000..e86d75535
--- /dev/null
+++ b/src/lib/mcp/errorHandler.test.ts
@@ -0,0 +1,225 @@
+/**
+ * Tests for error handling utilities
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { logAndFormatError, withErrorHandling, ErrorCategory } from "./errorHandler";
+import { ValidationError } from "./validation";
+import type { MCPToolResult } from "./types";
+
+describe("logAndFormatError", () => {
+  let consoleErrorSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    consoleErrorSpy.mockRestore();
+  });
+
+  it("should pass through ValidationError message directly", () => {
+    const error = new ValidationError("Invalid user ID format");
+    const result = logAndFormatError("testFunction", error);
+
+    expect(result).toEqual({
+      content: [{ type: "text", text: "Invalid user ID format" }],
+      isError: true,
+    });
+    expect(consoleErrorSpy).toHaveBeenCalled();
+  });
+
+  it("should generate error code for generic Error", () => {
+    const error = new Error("Something went wrong");
+    const result = logAndFormatError("testFunction", error);
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toMatch(/An error occurred \(code: GEN-ERR-\d{3}\)/);
+    expect(consoleErrorSpy).toHaveBeenCalled();
+  });
+
+  it("should use VALIDATION-001 code for ErrorCategory.VALIDATION", () => {
+    const error = new Error("Validation failed");
+    const result = logAndFormatError("testFunction", error, ErrorCategory.VALIDATION);
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toBe("An error occurred (code: VALIDATION-001). Check logs for details.");
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining("Code: VALIDATION-001"),
+      error
+    );
+  });
+
+  it("should use category-specific error code", () => {
+    const error = new Error("Chat not found");
+    const result = logAndFormatError("getChatInfo", error, ErrorCategory.CHAT);
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toMatch(/An error occurred \(code: CHAT-ERR-\d{3}\)/);
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining("CHAT-ERR-"),
+      error
+    );
+  });
+
+  it("should include context in console log", () => {
+    const error = new Error("Test error");
+    const context = { userId: 123, chatId: "456" };
+
+    logAndFormatError("sendMessage", error, ErrorCategory.MSG, context);
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining("userId=123, chatId=456"),
+      error
+    );
+  });
+
+  it("should work without category parameter", () => {
+    const error = new Error("Generic error");
+    const result = logAndFormatError("genericFunction", error);
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toMatch(/An error occurred \(code: GEN-ERR-\d{3}\)/);
+  });
+
+  it("should work without context parameter", () => {
+    const error = new Error("Test error");
+    const result = logAndFormatError("testFunction", error, ErrorCategory.CONTACT);
+
+    expect(result.isError).toBe(true);
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining("[MCP] Error in testFunction ()"),
+      error
+    );
+  });
+
+  it("should handle different error categories", () => {
+    const categories = [
+      ErrorCategory.CHAT,
+      ErrorCategory.MSG,
+      ErrorCategory.CONTACT,
+      ErrorCategory.GROUP,
+      ErrorCategory.MEDIA,
+      ErrorCategory.PROFILE,
+      ErrorCategory.AUTH,
+      ErrorCategory.ADMIN,
+      ErrorCategory.SEARCH,
+      ErrorCategory.DRAFT,
+    ];
+
+    categories.forEach((category) => {
+      const error = new Error("Test");
+      const result = logAndFormatError("test", error, category);
+
+      expect(result.isError).toBe(true);
+      expect(result.content[0].text).toMatch(
+        new RegExp(`An error occurred \\(code: ${category}-ERR-\\d{3}\\)`)
+      );
+    });
+  });
+});
+
+describe("withErrorHandling", () => {
+  let consoleErrorSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    consoleErrorSpy.mockRestore();
+  });
+
+  it("should return result when async function succeeds", async () => {
+    const successResult: MCPToolResult = {
+      content: [{ type: "text", text: "Success" }],
+    };
+
+    const fn = async () => successResult;
+    const wrapped = withErrorHandling(fn);
+    const result = await wrapped();
+
+    expect(result).toEqual(successResult);
+    expect(consoleErrorSpy).not.toHaveBeenCalled();
+  });
+
+  it("should catch and format errors from async function", async () => {
+    const fn = async () => {
+      throw new Error("Function failed");
+    };
+
+    const wrapped = withErrorHandling(fn as any, ErrorCategory.CHAT);
+    const result: any = await wrapped();
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toMatch(/An error occurred \(code: CHAT-ERR-\d{3}\)/);
+    expect(consoleErrorSpy).toHaveBeenCalled();
+  });
+
+  it("should catch ValidationError and pass through message", async () => {
+    const fn = async () => {
+      throw new ValidationError("Invalid input parameter");
+    };
+
+    const wrapped = withErrorHandling(fn as any);
+    const result: any = await wrapped();
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toBe("Invalid input parameter");
+  });
+
+  it("should handle non-Error throws by converting to Error", async () => {
+    const fn = async () => {
+      throw "String error";
+    };
+
+    const wrapped = withErrorHandling(fn as any);
+    const result: any = await wrapped();
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toMatch(/An error occurred \(code: GEN-ERR-\d{3}\)/);
+  });
+
+  it("should preserve function arguments in error context", async () => {
+    const fn = async (_chatId: number, _message: string) => {
+      throw new Error("Test error");
+    };
+
+    const wrapped = withErrorHandling(fn as any, ErrorCategory.MSG);
+    await wrapped(123, "Hello");
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining('args='),
+      expect.any(Error)
+    );
+  });
+
+  it("should use function name in error code generation", async () => {
+    async function namedFunction() {
+      throw new Error("Test");
+    }
+
+    const wrapped = withErrorHandling(namedFunction as any);
+    await wrapped();
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining("[MCP] Error in namedFunction"),
+      expect.any(Error)
+    );
+  });
+
+  it("should handle anonymous functions with 'unknown' name", async () => {
+    const wrapped = withErrorHandling((() => {
+      const f = async () => { throw new Error("Test"); };
+      Object.defineProperty(f, "name", { value: "" });
+      return f;
+    })() as any);
+
+    await wrapped();
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining("[MCP] Error in unknown"),
+      expect.any(Error)
+    );
+  });
+});
\ No newline at end of file
diff --git a/src/lib/mcp/rateLimiter.test.ts b/src/lib/mcp/rateLimiter.test.ts
new file mode 100644
index 000000000..4a5fe8e3e
--- /dev/null
+++ b/src/lib/mcp/rateLimiter.test.ts
@@ -0,0 +1,284 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import {
+  classifyTool,
+  isStateOnlyTool,
+  isHeavyTool,
+  enforceRateLimit,
+  resetRequestCallCount,
+  RATE_LIMIT_CONFIG,
+} from "./rateLimiter";
+
+// Mock the logger module to avoid console output during tests
+vi.mock("./logger", () => ({
+  mcpLog: vi.fn(),
+  mcpWarn: vi.fn(),
+}));
+
+describe("RATE_LIMIT_CONFIG", () => {
+  it("has correct configuration values", () => {
+    expect(RATE_LIMIT_CONFIG.API_READ_DELAY_MS).toBe(500);
+    expect(RATE_LIMIT_CONFIG.API_WRITE_DELAY_MS).toBe(1000);
+    expect(RATE_LIMIT_CONFIG.MAX_CALLS_PER_MINUTE).toBe(30);
+    expect(RATE_LIMIT_CONFIG.MAX_CALLS_PER_REQUEST).toBe(20);
+  });
+});
+
+describe("classifyTool", () => {
+  it("classifies known state_only tools correctly", () => {
+    expect(classifyTool("get_chats")).toBe("state_only");
+    expect(classifyTool("list_chats")).toBe("state_only");
+    expect(classifyTool("get_chat")).toBe("state_only");
+    expect(classifyTool("get_messages")).toBe("state_only");
+    expect(classifyTool("list_messages")).toBe("state_only");
+    expect(classifyTool("get_me")).toBe("state_only");
+    expect(classifyTool("get_message_context")).toBe("state_only");
+    expect(classifyTool("get_history")).toBe("state_only");
+  });
+
+  it("classifies known api_write tools correctly", () => {
+    expect(classifyTool("send_message")).toBe("api_write");
+    expect(classifyTool("edit_message")).toBe("api_write");
+    expect(classifyTool("delete_message")).toBe("api_write");
+    expect(classifyTool("forward_message")).toBe("api_write");
+    expect(classifyTool("create_group")).toBe("api_write");
+    expect(classifyTool("ban_user")).toBe("api_write");
+  });
+
+  it("classifies known api_read tools correctly", () => {
+    expect(classifyTool("list_contacts")).toBe("api_read");
+    expect(classifyTool("search_contacts")).toBe("api_read");
+    expect(classifyTool("get_participants")).toBe("api_read");
+    expect(classifyTool("get_admins")).toBe("api_read");
+    expect(classifyTool("search_messages")).toBe("api_read");
+  });
+
+  it("defaults unknown tools to api_read", () => {
+    expect(classifyTool("unknown_tool_xyz")).toBe("api_read");
+    expect(classifyTool("random_tool_123")).toBe("api_read");
+  });
+});
+
+describe("isStateOnlyTool", () => {
+  it("returns true for state_only tools", () => {
+    expect(isStateOnlyTool("get_chats")).toBe(true);
+    expect(isStateOnlyTool("list_messages")).toBe(true);
+    expect(isStateOnlyTool("get_me")).toBe(true);
+  });
+
+  it("returns false for api_write tools", () => {
+    expect(isStateOnlyTool("send_message")).toBe(false);
+    expect(isStateOnlyTool("edit_message")).toBe(false);
+  });
+
+  it("returns false for api_read tools", () => {
+    expect(isStateOnlyTool("list_contacts")).toBe(false);
+    expect(isStateOnlyTool("search_contacts")).toBe(false);
+  });
+
+  it("returns false for unknown tools", () => {
+    expect(isStateOnlyTool("unknown_tool")).toBe(false);
+  });
+});
+
+describe("isHeavyTool", () => {
+  it("returns true for api_write tools", () => {
+    expect(isHeavyTool("send_message")).toBe(true);
+    expect(isHeavyTool("edit_message")).toBe(true);
+    expect(isHeavyTool("delete_message")).toBe(true);
+    expect(isHeavyTool("create_group")).toBe(true);
+  });
+
+  it("returns false for state_only tools", () => {
+    expect(isHeavyTool("get_chats")).toBe(false);
+    expect(isHeavyTool("list_messages")).toBe(false);
+  });
+
+  it("returns false for api_read tools", () => {
+    expect(isHeavyTool("list_contacts")).toBe(false);
+    expect(isHeavyTool("search_contacts")).toBe(false);
+  });
+
+  it("returns false for unknown tools", () => {
+    expect(isHeavyTool("unknown_tool")).toBe(false);
+  });
+});
+
+describe("enforceRateLimit", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    resetRequestCallCount();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.useRealTimers();
+  });
+
+  it("allows state_only tools without any delay or limit", async () => {
+    const start = Date.now();
+
+    await enforceRateLimit("get_chats");
+    await enforceRateLimit("list_messages");
+    await enforceRateLimit("get_me");
+
+    const elapsed = Date.now() - start;
+    expect(elapsed).toBe(0); // No time should have passed
+  });
+
+  it("enforces per-request cap for api_read tools", async () => {
+    // Call enforceRateLimit 20 times (the max)
+    for (let i = 0; i < RATE_LIMIT_CONFIG.MAX_CALLS_PER_REQUEST; i++) {
+      await enforceRateLimit("list_contacts");
+      vi.advanceTimersByTime(RATE_LIMIT_CONFIG.API_READ_DELAY_MS);
+    }
+
+    // The 21st call should throw
+    await expect(enforceRateLimit("list_contacts")).rejects.toThrow(
+      /exceeded 20 API tool calls per request/,
+    );
+  });
+
+  it("enforces per-request cap for api_write tools", async () => {
+    // Call enforceRateLimit 20 times (the max)
+    for (let i = 0; i < RATE_LIMIT_CONFIG.MAX_CALLS_PER_REQUEST; i++) {
+      const promise = enforceRateLimit("send_message");
+      await vi.runAllTimersAsync();
+      await promise;
+    }
+
+    // The 21st call should throw
+    await expect(enforceRateLimit("send_message")).rejects.toThrow(
+      /exceeded 20 API tool calls per request/,
+    );
+  });
+
+  it("does not enforce per-request cap on state_only tools", async () => {
+    // Call state_only tools many more times than the cap
+    for (let i = 0; i < 50; i++) {
+      await enforceRateLimit("get_chats");
+    }
+
+    // Should not throw
+    expect(true).toBe(true);
+  });
+
+  it("resets per-request counter when resetRequestCallCount is called", async () => {
+    // Use up the budget
+    for (let i = 0; i < RATE_LIMIT_CONFIG.MAX_CALLS_PER_REQUEST; i++) {
+      const promise = enforceRateLimit("list_contacts");
+      await vi.runAllTimersAsync();
+      await promise;
+    }
+
+    // Next call should fail
+    await expect(enforceRateLimit("list_contacts")).rejects.toThrow(
+      /exceeded 20 API tool calls per request/,
+    );
+
+    // Reset the counter
+    resetRequestCallCount();
+
+    // Now it should work again
+    const promise = enforceRateLimit("list_contacts");
+    await vi.runAllTimersAsync();
+    await expect(promise).resolves.toBeUndefined();
+  });
+
+  it("enforces inter-call delay for api_read tools", async () => {
+    const promise1 = enforceRateLimit("list_contacts");
+    await vi.runAllTimersAsync();
+    await promise1; // First call goes through immediately
+
+    const start = Date.now();
+    const promise2 = enforceRateLimit("list_contacts");
+
+    // The second call should be delayed by API_READ_DELAY_MS
+    expect(Date.now() - start).toBe(0); // Promise created but not resolved yet
+
+    // Advance time and run all timers
+    await vi.runAllTimersAsync();
+    await promise2;
+
+    expect(Date.now() - start).toBeGreaterThanOrEqual(
+      RATE_LIMIT_CONFIG.API_READ_DELAY_MS,
+    );
+  });
+
+  it("enforces inter-call delay for api_write tools", async () => {
+    const promise1 = enforceRateLimit("send_message");
+    await vi.runAllTimersAsync();
+    await promise1; // First call goes through immediately
+
+    const start = Date.now();
+    const promise2 = enforceRateLimit("send_message");
+
+    // The second call should be delayed by API_WRITE_DELAY_MS
+    expect(Date.now() - start).toBe(0);
+
+    // Advance time and run all timers
+    await vi.runAllTimersAsync();
+    await promise2;
+
+    expect(Date.now() - start).toBeGreaterThanOrEqual(
+      RATE_LIMIT_CONFIG.API_WRITE_DELAY_MS,
+    );
+  });
+
+  it("enforces per-minute sliding window cap", async () => {
+    // Make MAX_CALLS_PER_MINUTE calls within the window
+    // Note: We need to reset the per-request counter periodically since MAX_CALLS_PER_MINUTE (30) > MAX_CALLS_PER_REQUEST (20)
+    for (let i = 0; i < RATE_LIMIT_CONFIG.MAX_CALLS_PER_MINUTE; i++) {
+      // Reset every 15 calls to avoid hitting per-request limit
+      if (i > 0 && i % 15 === 0) {
+        resetRequestCallCount();
+      }
+      const promise = enforceRateLimit("list_contacts");
+      await vi.runAllTimersAsync();
+      await promise;
+    }
+
+    // Reset again for the final test call
+    resetRequestCallCount();
+
+    // The next call should wait until the oldest entry expires (60 seconds from first call)
+    // The implementation waits for: oldestTimestamp + 60_000 - now + 50
+    const promise = enforceRateLimit("list_contacts");
+
+    // Check that promise hasn't resolved yet
+    let resolved = false;
+    void promise.then(() => {
+      resolved = true;
+    });
+
+    // Let microtasks run
+    await Promise.resolve();
+    expect(resolved).toBe(false);
+
+    // Now advance time past the 60-second window and run timers
+    await vi.runAllTimersAsync();
+
+    // Promise should now resolve
+    await promise;
+    expect(resolved).toBe(true);
+  });
+
+  it("counts both api_read and api_write towards per-request cap", async () => {
+    // Mix of read and write calls
+    for (let i = 0; i < 10; i++) {
+      const promise = enforceRateLimit("list_contacts");
+      await vi.runAllTimersAsync();
+      await promise;
+    }
+
+    for (let i = 0; i < 10; i++) {
+      const promise = enforceRateLimit("send_message");
+      await vi.runAllTimersAsync();
+      await promise;
+    }
+
+    // Total is 20, so the next call should throw
+    await expect(enforceRateLimit("list_contacts")).rejects.toThrow(
+      /exceeded 20 API tool calls per request/,
+    );
+  });
+});
diff --git a/src/lib/mcp/skills/bulk.ts b/src/lib/mcp/skills/bulk.ts
index 5af3bba1d..ab59abbaf 100644
--- a/src/lib/mcp/skills/bulk.ts
+++ b/src/lib/mcp/skills/bulk.ts
@@ -7,7 +7,7 @@
 
 import type { MCPTool, MCPToolResult } from "../types";
 import type { ExtraTool } from "./types";
-import * as telegramApi from "../telegram/telegramApi";
+import { sendMessage } from "../telegram/api/sendMessage";
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -193,7 +193,7 @@ async function executeBulkSendMessage(
 
   for (const chatId of chatIds) {
     try {
-      await telegramApi.sendMessage(chatId, message);
+      await sendMessage(chatId, message);
       successCount++;
       await sleep(BATCH_DELAY_MS);
     } catch (error) {
@@ -227,7 +227,7 @@ async function executeBulkArchiveChats(
     };
   }
 
-  // Archive is not directly available in telegramApi yet — return planned result
+  // Archive API integration pending — stubbed for now
   return {
     content: [
       {
diff --git a/src/lib/mcp/telegram/api/__tests__/getChats.test.ts b/src/lib/mcp/telegram/api/__tests__/getChats.test.ts
new file mode 100644
index 000000000..b6dfc1879
--- /dev/null
+++ b/src/lib/mcp/telegram/api/__tests__/getChats.test.ts
@@ -0,0 +1,196 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { getChats } from "../getChats";
+import type { TelegramChat } from "../../../../../store/telegram/types";
+
+// Mock dependencies
+const mockClient = {
+  invoke: vi.fn(),
+  getInputEntity: vi.fn(),
+  getMe: vi.fn(),
+  sendMessage: vi.fn(),
+};
+
+vi.mock("../../../../../services/mtprotoService", () => ({
+  mtprotoService: {
+    getClient: vi.fn(() => mockClient),
+    withFloodWaitHandling: vi.fn(async (fn: any) => await fn()),
+    isReady: vi.fn(() => true),
+    isClientConnected: vi.fn(() => true),
+    sendMessage: vi.fn(),
+  },
+}));
+
+vi.mock("../../../../../store", () => ({
+  store: {
+    getState: vi.fn(() => ({
+      user: { user: { _id: "u1" } },
+      telegram: {
+        byUser: {
+          u1: {
+            chats: {},
+            chatsOrder: [],
+            messages: {},
+            messagesOrder: {},
+            currentUser: null,
+          },
+        },
+      },
+    })),
+  },
+}));
+
+vi.mock("../../../../../store/telegramSelectors", () => ({
+  selectTelegramUserState: vi.fn(() => ({
+    chats: {},
+    chatsOrder: [],
+    messages: {},
+    messagesOrder: {},
+    currentUser: null,
+  })),
+  selectCurrentUser: vi.fn(() => null),
+  selectOrderedChats: vi.fn(() => []),
+}));
+
+vi.mock("../../../rateLimiter", () => ({
+  enforceRateLimit: vi.fn(),
+  resetRequestCallCount: vi.fn(),
+}));
+
+vi.mock("../helpers", async (importOriginal) => {
+  const original = (await importOriginal()) as any;
+  return {
+    ...original,
+    getOrderedChats: vi.fn(() => []),
+    apiDialogToTelegramChat: original.apiDialogToTelegramChat,
+  };
+});
+
+describe("getChats", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should return cached data when cache hit occurs", async () => {
+    const mockCachedChats: TelegramChat[] = [
+      {
+        id: "1",
+        title: "Cached Chat 1",
+        type: "private",
+        unreadCount: 0,
+        isPinned: false,
+      },
+      {
+        id: "2",
+        title: "Cached Chat 2",
+        type: "group",
+        unreadCount: 5,
+        isPinned: true,
+      },
+    ];
+
+    const { getOrderedChats } = await import("../helpers");
+    vi.mocked(getOrderedChats).mockReturnValueOnce(mockCachedChats);
+
+    const result = await getChats(20);
+
+    expect(result.data).toEqual(mockCachedChats);
+    expect(result.fromCache).toBe(true);
+
+    const { mtprotoService } = await import(
+      "../../../../../services/mtprotoService"
+    );
+    expect(mtprotoService.getClient).not.toHaveBeenCalled();
+  });
+
+  it("should call API when cache is empty", async () => {
+    const { getOrderedChats } = await import("../helpers");
+    vi.mocked(getOrderedChats).mockReturnValueOnce([]);
+
+    const { enforceRateLimit } = await import("../../../rateLimiter");
+    vi.mocked(enforceRateLimit).mockResolvedValueOnce(undefined);
+
+    const mockApiDialogs = {
+      dialogs: [
+        {
+          peer: { className: "PeerChannel", channelId: 123n },
+          unreadCount: 5,
+          pinned: false,
+        },
+      ],
+      chats: [
+        {
+          id: 123n,
+          title: "API Chat",
+          accessHash: 456n,
+          megagroup: false,
+        },
+      ],
+      users: [],
+    };
+
+    mockClient.invoke.mockResolvedValueOnce(mockApiDialogs);
+
+    const result = await getChats(20);
+
+    expect(result.fromCache).toBe(false);
+    expect(enforceRateLimit).toHaveBeenCalledWith("__api_fallback_chats");
+    expect(mockClient.invoke).toHaveBeenCalledWith(
+      expect.objectContaining({
+        className: "messages.GetDialogs",
+      })
+    );
+  });
+
+  it("should return empty array when API fails", async () => {
+    const { getOrderedChats } = await import("../helpers");
+    vi.mocked(getOrderedChats).mockReturnValueOnce([]);
+
+    const { enforceRateLimit } = await import("../../../rateLimiter");
+    vi.mocked(enforceRateLimit).mockResolvedValueOnce(undefined);
+
+    mockClient.invoke.mockRejectedValueOnce(new Error("API Error"));
+
+    const result = await getChats(20);
+
+    expect(result.data).toEqual([]);
+    expect(result.fromCache).toBe(false);
+  });
+
+  it("should return empty array when rate limit is rejected", async () => {
+    const { getOrderedChats } = await import("../helpers");
+    vi.mocked(getOrderedChats).mockReturnValueOnce([]);
+
+    const { enforceRateLimit } = await import("../../../rateLimiter");
+    vi.mocked(enforceRateLimit).mockRejectedValueOnce(
+      new Error("Rate limit exceeded")
+    );
+
+    const result = await getChats(20);
+
+    expect(result.data).toEqual([]);
+    expect(result.fromCache).toBe(false);
+
+    const { mtprotoService } = await import(
+      "../../../../../services/mtprotoService"
+    );
+    expect(mtprotoService.getClient).not.toHaveBeenCalled();
+  });
+
+  it("should respect custom limit parameter", async () => {
+    const mockCachedChats: TelegramChat[] = Array.from({ length: 50 }, (_, i) => ({
+      id: String(i),
+      title: `Chat ${i}`,
+      type: "private",
+      unreadCount: 0,
+      isPinned: false,
+    }));
+
+    const { getOrderedChats } = await import("../helpers");
+    vi.mocked(getOrderedChats).mockReturnValueOnce(mockCachedChats.slice(0, 50));
+
+    const result = await getChats(50);
+
+    expect(getOrderedChats).toHaveBeenCalledWith(50);
+    expect(result.data).toHaveLength(50);
+  });
+});
diff --git a/src/lib/mcp/telegram/api/__tests__/getCurrentUser.test.ts b/src/lib/mcp/telegram/api/__tests__/getCurrentUser.test.ts
new file mode 100644
index 000000000..4e82a4d66
--- /dev/null
+++ b/src/lib/mcp/telegram/api/__tests__/getCurrentUser.test.ts
@@ -0,0 +1,195 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { getCurrentUser } from "../getCurrentUser";
+import type { TelegramUser } from "../../../../../store/telegram/types";
+
+// Mock dependencies
+const mockClient = {
+  invoke: vi.fn(),
+  getInputEntity: vi.fn(),
+  getMe: vi.fn(),
+  sendMessage: vi.fn(),
+};
+
+vi.mock("../../../../../services/mtprotoService", () => ({
+  mtprotoService: {
+    getClient: vi.fn(() => mockClient),
+    withFloodWaitHandling: vi.fn(async (fn: any) => await fn()),
+    isReady: vi.fn(() => true),
+    isClientConnected: vi.fn(() => true),
+    sendMessage: vi.fn(),
+  },
+}));
+
+vi.mock("../../../../../store", () => ({
+  store: {
+    getState: vi.fn(() => ({
+      user: { user: { _id: "u1" } },
+      telegram: {
+        byUser: {
+          u1: {
+            chats: {},
+            chatsOrder: [],
+            messages: {},
+            messagesOrder: {},
+            currentUser: null,
+          },
+        },
+      },
+    })),
+  },
+}));
+
+vi.mock("../../../../../store/telegramSelectors", () => ({
+  selectTelegramUserState: vi.fn(() => ({
+    chats: {},
+    chatsOrder: [],
+    messages: {},
+    messagesOrder: {},
+    currentUser: null,
+  })),
+  selectCurrentUser: vi.fn(() => null),
+  selectOrderedChats: vi.fn(() => []),
+}));
+
+vi.mock("../../../rateLimiter", () => ({
+  enforceRateLimit: vi.fn(),
+  resetRequestCallCount: vi.fn(),
+}));
+
+vi.mock("../helpers", async (importOriginal) => {
+  const original = (await importOriginal()) as any;
+  return {
+    ...original,
+    getCurrentUser: vi.fn(() => undefined),
+  };
+});
+
+describe("getCurrentUser", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should return cached user when cache hit occurs", async () => {
+    const mockCachedUser: TelegramUser = {
+      id: "self123",
+      firstName: "John",
+      lastName: "Doe",
+      username: "johndoe",
+      phoneNumber: "+1234567890",
+      isBot: false,
+    };
+
+    const { getCurrentUser: getCurrentUserHelper } = await import("../helpers");
+    vi.mocked(getCurrentUserHelper).mockReturnValueOnce(mockCachedUser);
+
+    const result = await getCurrentUser();
+
+    expect(result.data).toEqual(mockCachedUser);
+    expect(result.fromCache).toBe(true);
+
+    const { mtprotoService } = await import(
+      "../../../../../services/mtprotoService"
+    );
+    expect(mtprotoService.getClient).not.toHaveBeenCalled();
+  });
+
+  it("should call API when cache is empty", async () => {
+    const { getCurrentUser: getCurrentUserHelper } = await import("../helpers");
+    vi.mocked(getCurrentUserHelper).mockReturnValueOnce(undefined);
+
+    const { enforceRateLimit } = await import("../../../rateLimiter");
+    vi.mocked(enforceRateLimit).mockResolvedValueOnce(undefined);
+
+    const mockApiUser = {
+      id: 123n,
+      firstName: "API User",
+      lastName: "Test",
+      username: "apiuser",
+      phone: "+9876543210",
+    };
+
+    mockClient.getMe.mockResolvedValueOnce(mockApiUser);
+
+    const result = await getCurrentUser();
+
+    expect(result.fromCache).toBe(false);
+    expect(result.data).toBeDefined();
+    expect(result.data?.id).toBe("123");
+    expect(result.data?.firstName).toBe("API User");
+    expect(enforceRateLimit).toHaveBeenCalledWith("__api_fallback_me");
+  });
+
+  it("should return undefined when API returns null", async () => {
+    const { getCurrentUser: getCurrentUserHelper } = await import("../helpers");
+    vi.mocked(getCurrentUserHelper).mockReturnValueOnce(undefined);
+
+    const { enforceRateLimit } = await import("../../../rateLimiter");
+    vi.mocked(enforceRateLimit).mockResolvedValueOnce(undefined);
+
+    mockClient.getMe.mockResolvedValueOnce(null);
+
+    const result = await getCurrentUser();
+
+    expect(result.data).toBeUndefined();
+    expect(result.fromCache).toBe(false);
+  });
+
+  it("should return undefined when API fails", async () => {
+    const { getCurrentUser: getCurrentUserHelper } = await import("../helpers");
+    vi.mocked(getCurrentUserHelper).mockReturnValueOnce(undefined);
+
+    const { enforceRateLimit } = await import("../../../rateLimiter");
+    vi.mocked(enforceRateLimit).mockResolvedValueOnce(undefined);
+
+    mockClient.getMe.mockRejectedValueOnce(new Error("API Error"));
+
+    const result = await getCurrentUser();
+
+    expect(result.data).toBeUndefined();
+    expect(result.fromCache).toBe(false);
+  });
+
+  it("should return undefined when rate limit is rejected", async () => {
+    const { getCurrentUser: getCurrentUserHelper } = await import("../helpers");
+    vi.mocked(getCurrentUserHelper).mockReturnValueOnce(undefined);
+
+    const { enforceRateLimit } = await import("../../../rateLimiter");
+    vi.mocked(enforceRateLimit).mockRejectedValueOnce(
+      new Error("Rate limit exceeded")
+    );
+
+    const result = await getCurrentUser();
+
+    expect(result.data).toBeUndefined();
+    expect(result.fromCache).toBe(false);
+
+    const { mtprotoService } = await import(
+      "../../../../../services/mtprotoService"
+    );
+    expect(mtprotoService.getClient).not.toHaveBeenCalled();
+  });
+
+  it("should handle user with minimal fields", async () => {
+    const { getCurrentUser: getCurrentUserHelper } = await import("../helpers");
+    vi.mocked(getCurrentUserHelper).mockReturnValueOnce(undefined);
+
+    const { enforceRateLimit } = await import("../../../rateLimiter");
+    vi.mocked(enforceRateLimit).mockResolvedValueOnce(undefined);
+
+    const mockApiUser = {
+      id: 456n,
+      firstName: "MinimalUser",
+      // No lastName, username, or phone
+    };
+
+    mockClient.getMe.mockResolvedValueOnce(mockApiUser);
+
+    const result = await getCurrentUser();
+
+    expect(result.data).toBeDefined();
+    expect(result.data?.id).toBe("456");
+    expect(result.data?.firstName).toBe("MinimalUser");
+    expect(result.data?.lastName).toBeUndefined();
+    expect(result.data?.username).toBeUndefined();
+  });
+});
diff --git a/src/lib/mcp/telegram/api/__tests__/getMessages.test.ts b/src/lib/mcp/telegram/api/__tests__/getMessages.test.ts
new file mode 100644
index 000000000..ad5ac63de
--- /dev/null
+++ b/src/lib/mcp/telegram/api/__tests__/getMessages.test.ts
@@ -0,0 +1,260 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { getMessages } from "../getMessages";
+import type { TelegramMessage } from "../../../../../store/telegram/types";
+
+// Mock dependencies
+const mockClient = {
+  invoke: vi.fn(),
+  getInputEntity: vi.fn(),
+  getMe: vi.fn(),
+  sendMessage: vi.fn(),
+};
+
+vi.mock("../../../../../services/mtprotoService", () => ({
+  mtprotoService: {
+    getClient: vi.fn(() => mockClient),
+    withFloodWaitHandling: vi.fn(async (fn: any) => await fn()),
+    isReady: vi.fn(() => true),
+    isClientConnected: vi.fn(() => true),
+    sendMessage: vi.fn(),
+  },
+}));
+
+vi.mock("../../../../../store", () => ({
+  store: {
+    getState: vi.fn(() => ({
+      user: { user: { _id: "u1" } },
+      telegram: {
+        byUser: {
+          u1: {
+            chats: {},
+            chatsOrder: [],
+            messages: {},
+            messagesOrder: {},
+            currentUser: null,
+          },
+        },
+      },
+    })),
+  },
+}));
+
+vi.mock("../../../../../store/telegramSelectors", () => ({
+  selectTelegramUserState: vi.fn(() => ({
+    chats: {},
+    chatsOrder: [],
+    messages: {},
+    messagesOrder: {},
+    currentUser: null,
+  })),
+  selectCurrentUser: vi.fn(() => null),
+  selectOrderedChats: vi.fn(() => []),
+}));
+
+vi.mock("../../../rateLimiter", () => ({
+  enforceRateLimit: vi.fn(),
+  resetRequestCallCount: vi.fn(),
+}));
+
+vi.mock("../helpers", async (importOriginal) => {
+  const original = (await importOriginal()) as any;
+  return {
+    ...original,
+    getCachedMessages: vi.fn(() => undefined),
+    getChatById: vi.fn(() => ({
+      id: "1",
+      title: "Test Chat",
+      type: "private",
+      unreadCount: 0,
+      isPinned: false,
+    })),
+    apiMessageToTelegramMessage: original.apiMessageToTelegramMessage,
+  };
+});
+
+describe("getMessages", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should return cached messages when cache hit occurs", async () => {
+    const mockCachedMessages: TelegramMessage[] = [
+      {
+        id: "1",
+        chatId: "1",
+        message: "Cached message 1",
+        date: Date.now(),
+        fromId: "sender1",
+        fromName: "John",
+        isOutgoing: false,
+        isEdited: false,
+        isForwarded: false,
+      },
+      {
+        id: "2",
+        chatId: "1",
+        message: "Cached message 2",
+        date: Date.now(),
+        fromId: "sender2",
+        fromName: "Jane",
+        isOutgoing: true,
+        isEdited: false,
+        isForwarded: false,
+      },
+    ];
+
+    const { getCachedMessages } = await import("../helpers");
+    vi.mocked(getCachedMessages).mockReturnValueOnce(mockCachedMessages);
+
+    const result = await getMessages("1", 20);
+
+    expect(result.data).toEqual(mockCachedMessages);
+    expect(result.fromCache).toBe(true);
+
+    const { mtprotoService } = await import(
+      "../../../../../services/mtprotoService"
+    );
+    expect(mtprotoService.getClient).not.toHaveBeenCalled();
+  });
+
+  it("should call API when cache is empty and chat is found", async () => {
+    const { getCachedMessages, getChatById } = await import("../helpers");
+    vi.mocked(getCachedMessages).mockReturnValueOnce(undefined);
+    vi.mocked(getChatById).mockReturnValueOnce({
+      id: "1",
+      title: "Test Chat",
+      type: "private",
+      unreadCount: 0,
+      isPinned: false,
+    });
+
+    const { enforceRateLimit } = await import("../../../rateLimiter");
+    vi.mocked(enforceRateLimit).mockResolvedValueOnce(undefined);
+
+    const mockApiMessages = {
+      messages: [
+        {
+          id: 100,
+          peerId: { userId: 123n },
+          message: "API message",
+          date: Math.floor(Date.now() / 1000),
+          fromId: { userId: 456n },
+          out: false,
+        },
+      ],
+      chats: [],
+      users: [
+        {
+          id: 456n,
+          firstName: "API User",
+        },
+      ],
+    };
+
+    mockClient.getInputEntity.mockResolvedValueOnce({ className: "InputPeerUser", userId: 1n });
+    mockClient.invoke.mockResolvedValueOnce(mockApiMessages);
+
+    const result = await getMessages("1", 20);
+
+    expect(result.fromCache).toBe(false);
+    expect(enforceRateLimit).toHaveBeenCalledWith("__api_fallback_messages");
+    expect(mockClient.invoke).toHaveBeenCalledWith(
+      expect.objectContaining({
+        className: "messages.GetHistory",
+      })
+    );
+  });
+
+  it("should return empty array when chat is not found", async () => {
+    const { getCachedMessages, getChatById } = await import("../helpers");
+    vi.mocked(getCachedMessages).mockReturnValueOnce(undefined);
+    vi.mocked(getChatById).mockReturnValueOnce(undefined);
+
+    const result = await getMessages("999", 20);
+
+    expect(result.data).toEqual([]);
+    expect(result.fromCache).toBe(false);
+
+    const { mtprotoService } = await import(
+      "../../../../../services/mtprotoService"
+    );
+    expect(mtprotoService.getClient).not.toHaveBeenCalled();
+  });
+
+  it("should return empty array when API fails", async () => {
+    const { getCachedMessages, getChatById } = await import("../helpers");
+    vi.mocked(getCachedMessages).mockReturnValueOnce(undefined);
+    vi.mocked(getChatById).mockReturnValueOnce({
+      id: "1",
+      title: "Test Chat",
+      type: "private",
+      unreadCount: 0,
+      isPinned: false,
+    });
+
+    const { enforceRateLimit } = await import("../../../rateLimiter");
+    vi.mocked(enforceRateLimit).mockResolvedValueOnce(undefined);
+
+    mockClient.getInputEntity.mockResolvedValueOnce({ className: "InputPeerUser", userId: 1n });
+    mockClient.invoke.mockRejectedValueOnce(new Error("API Error"));
+
+    const result = await getMessages("1", 20);
+
+    expect(result.data).toEqual([]);
+    expect(result.fromCache).toBe(false);
+  });
+
+  it("should return empty array when rate limit is rejected", async () => {
+    const { getCachedMessages, getChatById } = await import("../helpers");
+    vi.mocked(getCachedMessages).mockReturnValueOnce(undefined);
+    vi.mocked(getChatById).mockReturnValueOnce({
+      id: "1",
+      title: "Test Chat",
+      type: "private",
+      unreadCount: 0,
+      isPinned: false,
+    });
+
+    const { enforceRateLimit } = await import("../../../rateLimiter");
+    vi.mocked(enforceRateLimit).mockRejectedValueOnce(
+      new Error("Rate limit exceeded")
+    );
+
+    const result = await getMessages("1", 20);
+
+    expect(result.data).toEqual([]);
+    expect(result.fromCache).toBe(false);
+
+    const { mtprotoService } = await import(
+      "../../../../../services/mtprotoService"
+    );
+    expect(mtprotoService.getClient).not.toHaveBeenCalled();
+  });
+
+  it("should respect custom limit parameter", async () => {
+    const mockCachedMessages: TelegramMessage[] = Array.from(
+      { length: 100 },
+      (_, i) => ({
+        id: String(i),
+        chatId: "1",
+        message: `Message ${i}`,
+        date: Date.now(),
+        fromId: "sender1",
+        fromName: "User",
+        isOutgoing: false,
+        isEdited: false,
+        isForwarded: false,
+      })
+    );
+
+    const { getCachedMessages } = await import("../helpers");
+    vi.mocked(getCachedMessages).mockReturnValueOnce(
+      mockCachedMessages.slice(0, 100)
+    );
+
+    const result = await getMessages("1", 100);
+
+    expect(getCachedMessages).toHaveBeenCalledWith("1", 100, 0);
+    expect(result.data).toHaveLength(100);
+  });
+});
diff --git a/src/lib/mcp/telegram/api/__tests__/helpers.test.ts b/src/lib/mcp/telegram/api/__tests__/helpers.test.ts
new file mode 100644
index 000000000..833674da0
--- /dev/null
+++ b/src/lib/mcp/telegram/api/__tests__/helpers.test.ts
@@ -0,0 +1,616 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import bigInt from "big-integer";
+import {
+  formatEntity,
+  formatMessage,
+  apiMessageToTelegramMessage,
+  apiDialogToTelegramChat,
+} from "../helpers";
+import type {
+  TelegramChat,
+  TelegramUser,
+  TelegramMessage,
+} from "../../../../../store/telegram/types";
+
+// Mock the store module
+vi.mock("../../../../../store", () => ({
+  store: {
+    getState: vi.fn(() => ({
+      telegram: {
+        byUser: {},
+      },
+    })),
+  },
+}));
+
+// Mock the selectors module
+vi.mock("../../../../../store/telegramSelectors", () => ({
+  selectChat: vi.fn(),
+  selectUser: vi.fn(),
+}));
+
+describe("formatEntity", () => {
+  describe("with TelegramChat", () => {
+    it("should format a channel chat", () => {
+      const chat: TelegramChat = {
+        id: "123",
+        title: "Test Channel",
+        type: "channel",
+        username: "testchannel",
+        unreadCount: 5,
+        isPinned: false,
+      };
+
+      const result = formatEntity(chat);
+
+      expect(result).toEqual({
+        id: "123",
+        name: "Test Channel",
+        type: "channel",
+        username: "testchannel",
+      });
+    });
+
+    it("should map supergroup to group type", () => {
+      const chat: TelegramChat = {
+        id: "456",
+        title: "Test Group",
+        type: "supergroup",
+        unreadCount: 0,
+        isPinned: true,
+      };
+
+      const result = formatEntity(chat);
+
+      expect(result).toEqual({
+        id: "456",
+        name: "Test Group",
+        type: "group",
+      });
+    });
+
+    it("should handle private chat type", () => {
+      const chat: TelegramChat = {
+        id: "789",
+        title: "John Doe",
+        type: "private",
+        unreadCount: 2,
+        isPinned: false,
+      };
+
+      const result = formatEntity(chat);
+
+      expect(result).toEqual({
+        id: "789",
+        name: "John Doe",
+        type: "private",
+      });
+    });
+
+    it("should use 'Unknown' when title is undefined", () => {
+      const chat: TelegramChat = {
+        id: "999",
+        title: undefined,
+        type: "group",
+        unreadCount: 0,
+        isPinned: false,
+      };
+
+      const result = formatEntity(chat);
+
+      expect(result).toEqual({
+        id: "999",
+        name: "Unknown",
+        type: "group",
+      });
+    });
+
+    it("should include username if present", () => {
+      const chat: TelegramChat = {
+        id: "111",
+        title: "Public Group",
+        type: "group",
+        username: "publicgroup",
+        unreadCount: 0,
+        isPinned: false,
+      };
+
+      const result = formatEntity(chat);
+
+      expect(result).toEqual({
+        id: "111",
+        name: "Public Group",
+        type: "group",
+        username: "publicgroup",
+      });
+    });
+  });
+
+  describe("with TelegramUser", () => {
+    it("should format a user with full name", () => {
+      const user: TelegramUser = {
+        id: "123",
+        firstName: "John",
+        lastName: "Doe",
+        username: "johndoe",
+        isBot: false,
+      };
+
+      const result = formatEntity(user);
+
+      expect(result).toEqual({
+        id: "123",
+        name: "John Doe",
+        type: "user",
+        username: "johndoe",
+      });
+    });
+
+    it("should format a user with only first name", () => {
+      const user: TelegramUser = {
+        id: "456",
+        firstName: "Alice",
+        isBot: false,
+      };
+
+      const result = formatEntity(user);
+
+      expect(result).toEqual({
+        id: "456",
+        name: "Alice",
+        type: "user",
+      });
+    });
+
+    it("should include phone number if present", () => {
+      const user: TelegramUser = {
+        id: "789",
+        firstName: "Bob",
+        lastName: "Smith",
+        phoneNumber: "+1234567890",
+        isBot: false,
+      };
+
+      const result = formatEntity(user);
+
+      expect(result).toEqual({
+        id: "789",
+        name: "Bob Smith",
+        type: "user",
+        phone: "+1234567890",
+      });
+    });
+
+    it("should handle bot users", () => {
+      const user: TelegramUser = {
+        id: "999",
+        firstName: "Bot",
+        username: "testbot",
+        isBot: true,
+      };
+
+      const result = formatEntity(user);
+
+      expect(result).toEqual({
+        id: "999",
+        name: "Bot",
+        type: "user",
+        username: "testbot",
+      });
+    });
+  });
+});
+
+describe("formatMessage", () => {
+  it("should format a basic message", () => {
+    const message: TelegramMessage = {
+      id: "1",
+      chatId: "123",
+      date: 1640000000,
+      message: "Hello, world!",
+      isOutgoing: false,
+      isEdited: false,
+      isForwarded: false,
+    };
+
+    const result = formatMessage(message);
+
+    expect(result).toEqual({
+      id: "1",
+      date: new Date(1640000000 * 1000).toISOString(),
+      text: "Hello, world!",
+    });
+  });
+
+  it("should include fromId when present", () => {
+    const message: TelegramMessage = {
+      id: "2",
+      chatId: "123",
+      date: 1640000000,
+      message: "Test message",
+      fromId: "456",
+      isOutgoing: false,
+      isEdited: false,
+      isForwarded: false,
+    };
+
+    const result = formatMessage(message);
+
+    expect(result).toEqual({
+      id: "2",
+      date: new Date(1640000000 * 1000).toISOString(),
+      text: "Test message",
+      from_id: "456",
+    });
+  });
+
+  it("should include media information when media exists", () => {
+    const message: TelegramMessage = {
+      id: "3",
+      chatId: "123",
+      date: 1640000000,
+      message: "Photo message",
+      media: { type: "photo" },
+      isOutgoing: false,
+      isEdited: false,
+      isForwarded: false,
+    };
+
+    const result = formatMessage(message);
+
+    expect(result).toEqual({
+      id: "3",
+      date: new Date(1640000000 * 1000).toISOString(),
+      text: "Photo message",
+      has_media: true,
+      media_type: "photo",
+    });
+  });
+
+  it("should not include media fields when media is absent", () => {
+    const message: TelegramMessage = {
+      id: "4",
+      chatId: "123",
+      date: 1640000000,
+      message: "Text only",
+      isOutgoing: false,
+      isEdited: false,
+      isForwarded: false,
+    };
+
+    const result = formatMessage(message);
+
+    expect(result.has_media).toBeUndefined();
+    expect(result.media_type).toBeUndefined();
+  });
+});
+
+describe("apiMessageToTelegramMessage", () => {
+  it("should convert a basic API message", () => {
+    const apiMsg = {
+      id: 42,
+      date: 1640000000,
+      message: "Hello",
+    };
+
+    const result = apiMessageToTelegramMessage(apiMsg as any, "123");
+
+    expect(result).toEqual({
+      id: "42",
+      chatId: "123",
+      date: 1640000000,
+      message: "Hello",
+      isOutgoing: false,
+      isEdited: false,
+      isForwarded: false,
+    });
+  });
+
+  it("should extract fromId from userId", () => {
+    const apiMsg = {
+      id: 42,
+      date: 1640000000,
+      message: "Test",
+      fromId: { userId: bigInt(456) },
+    };
+
+    const result = apiMessageToTelegramMessage(apiMsg as any, "123");
+
+    expect(result.fromId).toBe("456");
+  });
+
+  it("should include replyTo message ID", () => {
+    const apiMsg = {
+      id: 42,
+      date: 1640000000,
+      message: "Reply",
+      replyTo: { replyToMsgId: 10 },
+    };
+
+    const result = apiMessageToTelegramMessage(apiMsg as any, "123");
+
+    expect(result.replyToMessageId).toBe("10");
+  });
+
+  it("should detect media presence", () => {
+    const apiMsg = {
+      id: 42,
+      date: 1640000000,
+      message: "Photo",
+      media: { className: "MessageMediaPhoto" },
+    };
+
+    const result = apiMessageToTelegramMessage(apiMsg as any, "123");
+
+    expect(result.media).toEqual({ type: "MessageMediaPhoto" });
+  });
+
+  it("should set isEdited when editDate exists", () => {
+    const apiMsg = {
+      id: 42,
+      date: 1640000000,
+      message: "Edited",
+      editDate: 1640001000,
+    };
+
+    const result = apiMessageToTelegramMessage(apiMsg as any, "123");
+
+    expect(result.isEdited).toBe(true);
+  });
+
+  it("should set isForwarded when fwdFrom exists", () => {
+    const apiMsg = {
+      id: 42,
+      date: 1640000000,
+      message: "Forwarded",
+      fwdFrom: { fromId: bigInt(789) },
+    };
+
+    const result = apiMessageToTelegramMessage(apiMsg as any, "123");
+
+    expect(result.isForwarded).toBe(true);
+  });
+
+  it("should set isOutgoing when out flag is true", () => {
+    const apiMsg = {
+      id: 42,
+      date: 1640000000,
+      message: "Sent",
+      out: true,
+    };
+
+    const result = apiMessageToTelegramMessage(apiMsg as any, "123");
+
+    expect(result.isOutgoing).toBe(true);
+  });
+
+  it("should handle missing optional fields", () => {
+    const apiMsg = {
+      id: 42,
+      date: 1640000000,
+      message: "Minimal",
+    };
+
+    const result = apiMessageToTelegramMessage(apiMsg as any, "123");
+
+    expect(result.fromId).toBeUndefined();
+    expect(result.replyToMessageId).toBeUndefined();
+    expect(result.media).toBeUndefined();
+  });
+});
+
+describe("apiDialogToTelegramChat", () => {
+  const mockChatsById = new Map();
+  const mockUsersById = new Map();
+
+  beforeEach(() => {
+    mockChatsById.clear();
+    mockUsersById.clear();
+  });
+
+  it("should convert PeerUser dialog", () => {
+    const user = {
+      id: bigInt(123),
+      firstName: "John",
+      lastName: "Doe",
+      username: "johndoe",
+    };
+    mockUsersById.set("123", user);
+
+    const dialog = {
+      peer: { className: "PeerUser", userId: bigInt(123) },
+      unreadCount: 5,
+      pinned: true,
+    };
+
+    const result = apiDialogToTelegramChat(
+      dialog as any,
+      mockChatsById,
+      mockUsersById
+    );
+
+    expect(result).toEqual({
+      id: "123",
+      title: "John Doe",
+      type: "private",
+      username: "johndoe",
+      unreadCount: 5,
+      isPinned: true,
+    });
+  });
+
+  it("should convert PeerChat dialog", () => {
+    const chat = {
+      id: bigInt(456),
+      title: "Test Group",
+    };
+    mockChatsById.set("456", chat);
+
+    const dialog = {
+      peer: { className: "PeerChat", chatId: bigInt(456) },
+      unreadCount: 2,
+      pinned: false,
+    };
+
+    const result = apiDialogToTelegramChat(
+      dialog as any,
+      mockChatsById,
+      mockUsersById
+    );
+
+    expect(result).toEqual({
+      id: "456",
+      title: "Test Group",
+      type: "group",
+      unreadCount: 2,
+      isPinned: false,
+    });
+  });
+
+  it("should convert PeerChannel with megagroup flag", () => {
+    const channel = {
+      id: bigInt(789),
+      title: "Supergroup",
+      username: "mygroup",
+      megagroup: true,
+    };
+    mockChatsById.set("789", channel);
+
+    const dialog = {
+      peer: { className: "PeerChannel", channelId: bigInt(789) },
+      unreadCount: 0,
+      pinned: false,
+    };
+
+    const result = apiDialogToTelegramChat(
+      dialog as any,
+      mockChatsById,
+      mockUsersById
+    );
+
+    expect(result).toEqual({
+      id: "789",
+      title: "Supergroup",
+      type: "supergroup",
+      username: "mygroup",
+      unreadCount: 0,
+      isPinned: false,
+    });
+  });
+
+  it("should convert PeerChannel without megagroup as channel", () => {
+    const channel = {
+      id: bigInt(999),
+      title: "News Channel",
+      username: "news",
+      megagroup: false,
+    };
+    mockChatsById.set("999", channel);
+
+    const dialog = {
+      peer: { className: "PeerChannel", channelId: bigInt(999) },
+      unreadCount: 10,
+      pinned: true,
+    };
+
+    const result = apiDialogToTelegramChat(
+      dialog as any,
+      mockChatsById,
+      mockUsersById
+    );
+
+    expect(result).toEqual({
+      id: "999",
+      title: "News Channel",
+      type: "channel",
+      username: "news",
+      unreadCount: 10,
+      isPinned: true,
+    });
+  });
+
+  it("should return undefined for unknown peer type", () => {
+    const dialog = {
+      peer: {}, // No userId, chatId, or channelId
+      unreadCount: 0,
+      pinned: false,
+    };
+
+    const result = apiDialogToTelegramChat(
+      dialog as any,
+      mockChatsById,
+      mockUsersById
+    );
+
+    expect(result).toBeUndefined();
+  });
+
+  it("should use 'Unknown' title when raw entity is missing for PeerUser", () => {
+    const dialog = {
+      peer: { className: "PeerUser", userId: bigInt(123) },
+      unreadCount: 0,
+      pinned: false,
+    };
+    // User not in mockUsersById
+
+    const result = apiDialogToTelegramChat(
+      dialog as any,
+      mockChatsById,
+      mockUsersById
+    );
+
+    expect(result).toEqual({
+      id: "123",
+      title: "Unknown",
+      type: "private",
+      unreadCount: 0,
+      isPinned: false,
+    });
+  });
+
+  it("should use 'Unknown' title when raw entity is missing for PeerChat", () => {
+    const dialog = {
+      peer: { className: "PeerChat", chatId: bigInt(456) },
+      unreadCount: 0,
+      pinned: false,
+    };
+    // Chat not in mockChatsById
+
+    const result = apiDialogToTelegramChat(
+      dialog as any,
+      mockChatsById,
+      mockUsersById
+    );
+
+    expect(result).toEqual({
+      id: "456",
+      title: "Unknown",
+      type: "group",
+      unreadCount: 0,
+      isPinned: false,
+    });
+  });
+
+  it("should use 'Unknown' title when raw entity is missing for PeerChannel", () => {
+    const dialog = {
+      peer: { className: "PeerChannel", channelId: bigInt(789) },
+      unreadCount: 0,
+      pinned: false,
+    };
+    // Channel not in mockChatsById
+
+    const result = apiDialogToTelegramChat(
+      dialog as any,
+      mockChatsById,
+      mockUsersById
+    );
+
+    expect(result).toEqual({
+      id: "789",
+      title: "Unknown",
+      type: "channel",
+      unreadCount: 0,
+      isPinned: false,
+    });
+  });
+});
diff --git a/src/lib/mcp/telegram/api/__tests__/sendMessage.test.ts b/src/lib/mcp/telegram/api/__tests__/sendMessage.test.ts
new file mode 100644
index 000000000..0a815a796
--- /dev/null
+++ b/src/lib/mcp/telegram/api/__tests__/sendMessage.test.ts
@@ -0,0 +1,256 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { sendMessage } from "../sendMessage";
+
+// Mock dependencies
+vi.mock("../../../../../services/mtprotoService", () => {
+  const mockClient = {
+    invoke: vi.fn(),
+    getInputEntity: vi.fn(),
+    getMe: vi.fn(),
+    sendMessage: vi.fn(),
+  };
+
+  return {
+    mtprotoService: {
+      getClient: vi.fn(() => mockClient),
+      withFloodWaitHandling: vi.fn(async (fn: any) => await fn()),
+      isReady: vi.fn(() => true),
+      isClientConnected: vi.fn(() => true),
+      sendMessage: vi.fn(),
+    },
+  };
+});
+
+vi.mock("../../../../../store", () => ({
+  store: {
+    getState: vi.fn(() => ({
+      user: { user: { _id: "u1" } },
+      telegram: {
+        byUser: {
+          u1: {
+            chats: {},
+            chatsOrder: [],
+            messages: {},
+            messagesOrder: {},
+            currentUser: null,
+          },
+        },
+      },
+    })),
+  },
+}));
+
+vi.mock("../../../../../store/telegramSelectors", () => ({
+  selectTelegramUserState: vi.fn(() => ({
+    chats: {},
+    chatsOrder: [],
+    messages: {},
+    messagesOrder: {},
+    currentUser: null,
+  })),
+  selectCurrentUser: vi.fn(() => null),
+  selectOrderedChats: vi.fn(() => []),
+}));
+
+vi.mock("../../../rateLimiter", () => ({
+  enforceRateLimit: vi.fn(),
+  resetRequestCallCount: vi.fn(),
+}));
+
+vi.mock("../helpers", async (importOriginal) => {
+  const original = (await importOriginal()) as any;
+  return {
+    ...original,
+    getChatById: vi.fn(),
+  };
+});
+
+describe("sendMessage", () => {
+  let mockMtprotoService: any;
+  let mockClient: any;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    const mtproto = await import("../../../../../services/mtprotoService");
+    mockMtprotoService = mtproto.mtprotoService;
+    mockClient = mockMtprotoService.getClient();
+  });
+
+  it("should return undefined when chat is not found", async () => {
+    const { getChatById } = await import("../helpers");
+    vi.mocked(getChatById).mockReturnValueOnce(undefined);
+
+    const result = await sendMessage("999", "Hello");
+
+    expect(result.data).toBeUndefined();
+    expect(result.fromCache).toBe(false);
+    expect(mockMtprotoService.sendMessage).not.toHaveBeenCalled();
+  });
+
+  it("should use username when chat has username", async () => {
+    const { getChatById } = await import("../helpers");
+    vi.mocked(getChatById).mockReturnValueOnce({
+      id: "1",
+      title: "Test Chat",
+      type: "private",
+      username: "testuser",
+      unreadCount: 0,
+      isPinned: false,
+    });
+
+    mockMtprotoService.sendMessage.mockResolvedValueOnce({
+      id: 100,
+      randomId: 123n,
+    } as any);
+
+    const result = await sendMessage("1", "Hello with username");
+
+    expect(mockMtprotoService.sendMessage).toHaveBeenCalledWith(
+      "@testuser",
+      "Hello with username"
+    );
+    expect(result.data).toBeDefined();
+    expect(result.data?.id).toMatch(/^\d+$/); // Timestamp-based ID
+    expect(result.fromCache).toBe(false);
+  });
+
+  it("should use numeric ID when chat has no username", async () => {
+    const { getChatById } = await import("../helpers");
+    vi.mocked(getChatById).mockReturnValueOnce({
+      id: "123456",
+      title: "Test Chat",
+      type: "private",
+      unreadCount: 0,
+      isPinned: false,
+    });
+
+    mockMtprotoService.sendMessage.mockResolvedValueOnce({
+      id: 200,
+      randomId: 456n,
+    } as any);
+
+    const result = await sendMessage("123456", "Hello with ID");
+
+    expect(mockMtprotoService.sendMessage).toHaveBeenCalledWith(
+      "123456",
+      "Hello with ID"
+    );
+    expect(result.data).toBeDefined();
+    expect(result.data?.id).toMatch(/^\d+$/); // Timestamp-based ID
+  });
+
+  it("should use client.sendMessage with replyTo when replyToMessageId is provided", async () => {
+    const { getChatById } = await import("../helpers");
+    vi.mocked(getChatById).mockReturnValueOnce({
+      id: "1",
+      title: "Test Chat",
+      type: "private",
+      username: "testuser",
+      unreadCount: 0,
+      isPinned: false,
+    });
+
+    mockClient.sendMessage.mockResolvedValueOnce({
+      id: 300,
+      randomId: 789n,
+    });
+
+    const result = await sendMessage("1", "Reply message", 50);
+
+    expect(mockClient.sendMessage).toHaveBeenCalledWith("@testuser", {
+      message: "Reply message",
+      replyTo: 50,
+    });
+    expect(result.data).toBeDefined();
+    expect(result.data?.id).toMatch(/^\d+$/); // Timestamp-based ID
+  });
+
+  it("should handle API error by propagating exception", async () => {
+    const { getChatById } = await import("../helpers");
+    vi.mocked(getChatById).mockReturnValueOnce({
+      id: "1",
+      title: "Test Chat",
+      type: "private",
+      username: "testuser",
+      unreadCount: 0,
+      isPinned: false,
+    });
+
+    mockMtprotoService.sendMessage.mockRejectedValueOnce(
+      new Error("Network error")
+    );
+
+    await expect(sendMessage("1", "Failed message")).rejects.toThrow(
+      "Network error"
+    );
+  });
+
+  it("should handle empty message text", async () => {
+    const { getChatById } = await import("../helpers");
+    vi.mocked(getChatById).mockReturnValueOnce({
+      id: "1",
+      title: "Test Chat",
+      type: "private",
+      username: "testuser",
+      unreadCount: 0,
+      isPinned: false,
+    });
+
+    mockMtprotoService.sendMessage.mockResolvedValueOnce({
+      id: 400,
+      randomId: 999n,
+    } as any);
+
+    const result = await sendMessage("1", "");
+
+    expect(mockMtprotoService.sendMessage).toHaveBeenCalledWith("@testuser", "");
+    expect(result.data).toBeDefined();
+  });
+
+  it("should handle long message text", async () => {
+    const longMessage = "A".repeat(4096);
+    const { getChatById } = await import("../helpers");
+    vi.mocked(getChatById).mockReturnValueOnce({
+      id: "1",
+      title: "Test Chat",
+      type: "private",
+      unreadCount: 0,
+      isPinned: false,
+    });
+
+    mockMtprotoService.sendMessage.mockResolvedValueOnce({
+      id: 500,
+      randomId: 111n,
+    } as any);
+
+    const result = await sendMessage("1", longMessage);
+
+    expect(mockMtprotoService.sendMessage).toHaveBeenCalledWith("1", longMessage);
+    expect(result.data).toBeDefined();
+  });
+
+  it("should handle group chat without username", async () => {
+    const { getChatById } = await import("../helpers");
+    vi.mocked(getChatById).mockReturnValueOnce({
+      id: "-1001234567890",
+      title: "Test Group",
+      type: "group",
+      unreadCount: 0,
+      isPinned: false,
+    });
+
+    mockMtprotoService.sendMessage.mockResolvedValueOnce({
+      id: 600,
+      randomId: 222n,
+    } as any);
+
+    const result = await sendMessage("-1001234567890", "Group message");
+
+    expect(mockMtprotoService.sendMessage).toHaveBeenCalledWith(
+      "-1001234567890",
+      "Group message"
+    );
+    expect(result.data).toBeDefined();
+    expect(result.data?.id).toMatch(/^\d+$/); // Timestamp-based ID
+  });
+});
diff --git a/src/lib/mcp/telegram/api/addContact.ts b/src/lib/mcp/telegram/api/addContact.ts
new file mode 100644
index 000000000..7c7474e10
--- /dev/null
+++ b/src/lib/mcp/telegram/api/addContact.ts
@@ -0,0 +1,36 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import bigInt from "big-integer";
+
+export async function addContact(
+  phone: string,
+  firstName: string,
+  lastName?: string,
+): Promise<ApiResult<void>> {
+  if (!phone) {
+    throw new Error("phone is required");
+  }
+  if (!firstName) {
+    throw new Error("first_name is required");
+  }
+
+  const client = mtprotoService.getClient();
+
+  await mtprotoService.withFloodWaitHandling(async () => {
+    await client.invoke(
+      new Api.contacts.ImportContacts({
+        contacts: [
+          new Api.InputPhoneContact({
+            clientId: bigInt(0),
+            phone,
+            firstName,
+            lastName: lastName ?? "",
+          }),
+        ],
+      }),
+    );
+  });
+
+  return { data: undefined, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/apiCastHelpers.ts b/src/lib/mcp/telegram/api/apiCastHelpers.ts
similarity index 100%
rename from src/lib/mcp/telegram/apiCastHelpers.ts
rename to src/lib/mcp/telegram/api/apiCastHelpers.ts
diff --git a/src/lib/mcp/telegram/apiResultTypes.ts b/src/lib/mcp/telegram/api/apiResultTypes.ts
similarity index 100%
rename from src/lib/mcp/telegram/apiResultTypes.ts
rename to src/lib/mcp/telegram/api/apiResultTypes.ts
diff --git a/src/lib/mcp/telegram/api/archiveChat.ts b/src/lib/mcp/telegram/api/archiveChat.ts
new file mode 100644
index 000000000..c18c25e97
--- /dev/null
+++ b/src/lib/mcp/telegram/api/archiveChat.ts
@@ -0,0 +1,30 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import { getChatById } from "./helpers";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+
+export async function archiveChat(
+  chatId: string | number,
+): Promise<ApiResult<void>> {
+  const chat = getChatById(chatId);
+  if (!chat) throw new Error(`Chat not found: ${chatId}`);
+
+  const client = mtprotoService.getClient();
+  const entity = chat.username ? chat.username : chat.id;
+
+  await mtprotoService.withFloodWaitHandling(async () => {
+    const inputPeer = await client.getInputEntity(entity);
+    await client.invoke(
+      new Api.folders.EditPeerFolders({
+        folderPeers: [
+          new Api.InputFolderPeer({
+            peer: inputPeer,
+            folderId: 1, // 1 = Archive folder
+          }),
+        ],
+      }),
+    );
+  });
+
+  return { data: undefined as unknown as void, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/banUser.ts b/src/lib/mcp/telegram/api/banUser.ts
new file mode 100644
index 000000000..7735778d9
--- /dev/null
+++ b/src/lib/mcp/telegram/api/banUser.ts
@@ -0,0 +1,46 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import { toInputChannel, toInputPeer } from "./apiCastHelpers";
+import { getChatById } from "./helpers";
+
+export async function banUser(
+  chatId: string | number,
+  userId: string | number,
+): Promise<ApiResult<void>> {
+  const chat = getChatById(chatId);
+  if (!chat) {
+    throw new Error(`Chat not found: ${chatId}`);
+  }
+
+  if (chat.type !== "channel" && chat.type !== "supergroup") {
+    throw new Error("Ban is only available for channels/supergroups.");
+  }
+
+  const client = mtprotoService.getClient();
+  const entity = chat.username ? chat.username : chat.id;
+
+  await mtprotoService.withFloodWaitHandling(async () => {
+    const inputChannel = await client.getInputEntity(entity);
+    const inputUser = await client.getInputEntity(userId);
+    await client.invoke(
+      new Api.channels.EditBanned({
+        channel: toInputChannel(inputChannel),
+        participant: toInputPeer(inputUser),
+        bannedRights: new Api.ChatBannedRights({
+          viewMessages: true,
+          sendMessages: true,
+          sendMedia: true,
+          sendStickers: true,
+          sendGifs: true,
+          sendGames: true,
+          sendInline: true,
+          embedLinks: true,
+          untilDate: 0,
+        }),
+      }),
+    );
+  });
+
+  return { data: undefined, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/blockUser.ts b/src/lib/mcp/telegram/api/blockUser.ts
new file mode 100644
index 000000000..20669eb13
--- /dev/null
+++ b/src/lib/mcp/telegram/api/blockUser.ts
@@ -0,0 +1,15 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import { toInputPeer } from "./apiCastHelpers";
+
+export async function blockUser(userId: string | number): Promise<ApiResult<void>> {
+  const client = mtprotoService.getClient();
+
+  await mtprotoService.withFloodWaitHandling(async () => {
+    const inputUser = await client.getInputEntity(userId);
+    await client.invoke(new Api.contacts.Block({ id: toInputPeer(inputUser) }));
+  });
+
+  return { data: undefined, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/clearDraft.ts b/src/lib/mcp/telegram/api/clearDraft.ts
new file mode 100644
index 000000000..75c4a028e
--- /dev/null
+++ b/src/lib/mcp/telegram/api/clearDraft.ts
@@ -0,0 +1,34 @@
+/**
+ * API: Clear draft
+ */
+
+import { mtprotoService } from "../../../../services/mtprotoService";
+import { getChatById } from "./helpers";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+
+export async function clearDraft(
+  chatId: string | number,
+): Promise<ApiResult<void>> {
+  const chat = getChatById(chatId);
+  if (!chat) {
+    throw new Error(`Chat not found: ${chatId}`);
+  }
+
+  const client = mtprotoService.getClient();
+  const entity = chat.username
+    ? `@${chat.username.replace("@", "")}`
+    : chat.id;
+
+  await mtprotoService.withFloodWaitHandling(async () => {
+    const inputPeer = await client.getInputEntity(entity);
+    await client.invoke(
+      new Api.messages.SaveDraft({
+        peer: inputPeer,
+        message: "",
+      }),
+    );
+  });
+
+  return { data: undefined as unknown as void, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/createChannel.ts b/src/lib/mcp/telegram/api/createChannel.ts
new file mode 100644
index 000000000..de99e18ff
--- /dev/null
+++ b/src/lib/mcp/telegram/api/createChannel.ts
@@ -0,0 +1,30 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import type { ResultWithChats } from "./apiResultTypes";
+import { narrow } from "./apiCastHelpers";
+
+export async function createChannel(
+  title: string,
+  about?: string,
+  megagroup?: boolean,
+): Promise<ApiResult<{ id: string; type: string }>> {
+  const client = mtprotoService.getClient();
+
+  const result = await mtprotoService.withFloodWaitHandling(async () => {
+    return client.invoke(
+      new Api.channels.CreateChannel({
+        title,
+        about: about ?? "",
+        megagroup: megagroup ?? false,
+        broadcast: !megagroup,
+      }),
+    );
+  });
+
+  const channelId =
+    narrow<ResultWithChats>(result)?.chats?.[0]?.id ?? "unknown";
+  const type = megagroup ? "Supergroup" : "Channel";
+
+  return { data: { id: String(channelId), type }, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/createGroup.ts b/src/lib/mcp/telegram/api/createGroup.ts
new file mode 100644
index 000000000..cde5df2b1
--- /dev/null
+++ b/src/lib/mcp/telegram/api/createGroup.ts
@@ -0,0 +1,30 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import type { ResultWithChats } from "./apiResultTypes";
+import { toInputUser, narrow } from "./apiCastHelpers";
+
+export async function createGroup(
+  title: string,
+  userIds: string[],
+): Promise<ApiResult<{ id: string }>> {
+  if (userIds.length === 0) {
+    throw new Error("user_ids must not be empty");
+  }
+
+  const client = mtprotoService.getClient();
+
+  const users: Api.TypeInputUser[] = [];
+  for (const uid of userIds) {
+    const inputUser = await client.getInputEntity(String(uid));
+    users.push(toInputUser(inputUser));
+  }
+
+  const result = await mtprotoService.withFloodWaitHandling(async () => {
+    return client.invoke(new Api.messages.CreateChat({ title, users }));
+  });
+
+  const chatId = narrow<ResultWithChats>(result)?.chats?.[0]?.id ?? "unknown";
+
+  return { data: { id: String(chatId) }, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/createPoll.ts b/src/lib/mcp/telegram/api/createPoll.ts
new file mode 100644
index 000000000..e21dec8db
--- /dev/null
+++ b/src/lib/mcp/telegram/api/createPoll.ts
@@ -0,0 +1,54 @@
+/**
+ * API: Create poll
+ */
+
+import { mtprotoService } from "../../../../services/mtprotoService";
+import { getChatById } from "./helpers";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import bigInt from "big-integer";
+
+export async function createPoll(
+  chatId: string | number,
+  question: string,
+  options: string[],
+): Promise<ApiResult<void>> {
+  const chat = getChatById(chatId);
+  if (!chat) {
+    throw new Error(`Chat not found: ${chatId}`);
+  }
+
+  const client = mtprotoService.getClient();
+  const entity = chat.username
+    ? `@${chat.username.replace("@", "")}`
+    : chat.id;
+
+  await mtprotoService.withFloodWaitHandling(async () => {
+    const inputPeer = await client.getInputEntity(entity);
+    await client.invoke(
+      new Api.messages.SendMedia({
+        peer: inputPeer,
+        media: new Api.InputMediaPoll({
+          poll: new Api.Poll({
+            id: bigInt(0),
+            question: new Api.TextWithEntities({
+              text: question,
+              entities: [],
+            }),
+            answers: options.map(
+              (opt, i) =>
+                new Api.PollAnswer({
+                  text: new Api.TextWithEntities({ text: opt, entities: [] }),
+                  option: Buffer.from([i]),
+                }),
+            ),
+          }),
+        }),
+        message: "",
+        randomId: bigInt(Math.floor(Math.random() * Number.MAX_SAFE_INTEGER)),
+      }),
+    );
+  });
+
+  return { data: undefined as unknown as void, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/deleteChatPhoto.ts b/src/lib/mcp/telegram/api/deleteChatPhoto.ts
new file mode 100644
index 000000000..884ddd2c5
--- /dev/null
+++ b/src/lib/mcp/telegram/api/deleteChatPhoto.ts
@@ -0,0 +1,39 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import { getChatById } from "./helpers";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import bigInt from "big-integer";
+import { toInputChannel } from "./apiCastHelpers";
+
+export async function deleteChatPhoto(
+  chatId: string | number,
+): Promise<ApiResult<void>> {
+  const chat = getChatById(chatId);
+  if (!chat) throw new Error(`Chat not found: ${chatId}`);
+
+  const client = mtprotoService.getClient();
+  const entity = chat.username ? chat.username : chat.id;
+
+  if (chat.type === "channel" || chat.type === "supergroup") {
+    await mtprotoService.withFloodWaitHandling(async () => {
+      const inputChannel = await client.getInputEntity(entity);
+      await client.invoke(
+        new Api.channels.EditPhoto({
+          channel: toInputChannel(inputChannel),
+          photo: new Api.InputChatPhotoEmpty(),
+        }),
+      );
+    });
+  } else {
+    await mtprotoService.withFloodWaitHandling(async () => {
+      await client.invoke(
+        new Api.messages.EditChatPhoto({
+          chatId: bigInt(chat.id),
+          photo: new Api.InputChatPhotoEmpty(),
+        }),
+      );
+    });
+  }
+
+  return { data: undefined as unknown as void, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/deleteContact.ts b/src/lib/mcp/telegram/api/deleteContact.ts
new file mode 100644
index 000000000..e2867a718
--- /dev/null
+++ b/src/lib/mcp/telegram/api/deleteContact.ts
@@ -0,0 +1,19 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import { toInputUser } from "./apiCastHelpers";
+
+export async function deleteContact(userId: string | number): Promise<ApiResult<void>> {
+  const client = mtprotoService.getClient();
+
+  await mtprotoService.withFloodWaitHandling(async () => {
+    const inputUser = await client.getInputEntity(userId);
+    await client.invoke(
+      new Api.contacts.DeleteContacts({
+        id: [toInputUser(inputUser)],
+      }),
+    );
+  });
+
+  return { data: undefined, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/deleteMessage.ts b/src/lib/mcp/telegram/api/deleteMessage.ts
new file mode 100644
index 000000000..562b77792
--- /dev/null
+++ b/src/lib/mcp/telegram/api/deleteMessage.ts
@@ -0,0 +1,28 @@
+/**
+ * API: Delete message
+ */
+
+import { mtprotoService } from "../../../../services/mtprotoService";
+import { getChatById } from "./helpers";
+import type { ApiResult } from "./types";
+
+export async function deleteMessage(
+  chatId: string | number,
+  messageId: number,
+): Promise<ApiResult<void>> {
+  const chat = getChatById(chatId);
+  if (!chat) {
+    throw new Error(`Chat not found: ${chatId}`);
+  }
+
+  const entity = chat.username
+    ? `@${chat.username.replace("@", "")}`
+    : chat.id;
+  const client = mtprotoService.getClient();
+
+  await mtprotoService.withFloodWaitHandling(async () => {
+    await client.deleteMessages(entity, [messageId], { revoke: true });
+  });
+
+  return { data: undefined as unknown as void, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/deleteProfilePhoto.ts b/src/lib/mcp/telegram/api/deleteProfilePhoto.ts
new file mode 100644
index 000000000..0b5628663
--- /dev/null
+++ b/src/lib/mcp/telegram/api/deleteProfilePhoto.ts
@@ -0,0 +1,48 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import bigInt from "big-integer";
+import type { ApiPhoto } from "./apiResultTypes";
+import { narrow } from "./apiCastHelpers";
+
+export async function deleteProfilePhoto(): Promise<ApiResult<void>> {
+  const client = mtprotoService.getClient();
+
+  const photos = await mtprotoService.withFloodWaitHandling(async () => {
+    return client.invoke(
+      new Api.photos.GetUserPhotos({
+        userId: new Api.InputUserSelf(),
+        offset: 0,
+        maxId: bigInt(0),
+        limit: 1,
+      }),
+    );
+  });
+
+  if (
+    !photos ||
+    !("photos" in photos) ||
+    !Array.isArray(photos.photos) ||
+    photos.photos.length === 0
+  ) {
+    throw new Error("No profile photo to delete.");
+  }
+
+  const photo = narrow<ApiPhoto>(photos.photos[0]);
+
+  await mtprotoService.withFloodWaitHandling(async () => {
+    await client.invoke(
+      new Api.photos.DeletePhotos({
+        id: [
+          new Api.InputPhoto({
+            id: photo.id,
+            accessHash: photo.accessHash,
+            fileReference: photo.fileReference,
+          }),
+        ],
+      }),
+    );
+  });
+
+  return { data: undefined, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/demoteAdmin.ts b/src/lib/mcp/telegram/api/demoteAdmin.ts
new file mode 100644
index 000000000..3ef52349d
--- /dev/null
+++ b/src/lib/mcp/telegram/api/demoteAdmin.ts
@@ -0,0 +1,39 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import { toInputChannel, toInputUser } from "./apiCastHelpers";
+import { getChatById } from "./helpers";
+
+export async function demoteAdmin(
+  chatId: string | number,
+  userId: string | number,
+): Promise<ApiResult<void>> {
+  const chat = getChatById(chatId);
+  if (!chat) {
+    throw new Error(`Chat not found: ${chatId}`);
+  }
+
+  if (chat.type !== "channel" && chat.type !== "supergroup") {
+    throw new Error(
+      "Admin demotion is only available for channels/supergroups.",
+    );
+  }
+
+  const client = mtprotoService.getClient();
+  const entity = chat.username ? chat.username : chat.id;
+
+  await mtprotoService.withFloodWaitHandling(async () => {
+    const inputChannel = await client.getInputEntity(entity);
+    const inputUser = await client.getInputEntity(userId);
+    await client.invoke(
+      new Api.channels.EditAdmin({
+        channel: toInputChannel(inputChannel),
+        userId: toInputUser(inputUser),
+        adminRights: new Api.ChatAdminRights({}),
+        rank: "",
+      }),
+    );
+  });
+
+  return { data: undefined, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/editChatPhoto.ts b/src/lib/mcp/telegram/api/editChatPhoto.ts
new file mode 100644
index 000000000..9ebc945b6
--- /dev/null
+++ b/src/lib/mcp/telegram/api/editChatPhoto.ts
@@ -0,0 +1,10 @@
+import type { ApiResult } from "./types";
+
+export async function editChatPhoto(
+  _chatId: string | number,
+  _filePath: string,
+): Promise<ApiResult<void>> {
+  throw new Error(
+    "edit_chat_photo requires file upload which is not supported via MCP text interface. Use the Telegram client directly.",
+  );
+}
diff --git a/src/lib/mcp/telegram/api/editChatTitle.ts b/src/lib/mcp/telegram/api/editChatTitle.ts
new file mode 100644
index 000000000..0e4575f7b
--- /dev/null
+++ b/src/lib/mcp/telegram/api/editChatTitle.ts
@@ -0,0 +1,40 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import { getChatById } from "./helpers";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import bigInt from "big-integer";
+import { toInputChannel } from "./apiCastHelpers";
+
+export async function editChatTitle(
+  chatId: string | number,
+  title: string,
+): Promise<ApiResult<void>> {
+  const chat = getChatById(chatId);
+  if (!chat) throw new Error(`Chat not found: ${chatId}`);
+
+  const client = mtprotoService.getClient();
+  const entity = chat.username ? chat.username : chat.id;
+
+  if (chat.type === "channel" || chat.type === "supergroup") {
+    await mtprotoService.withFloodWaitHandling(async () => {
+      const inputChannel = await client.getInputEntity(entity);
+      await client.invoke(
+        new Api.channels.EditTitle({
+          channel: toInputChannel(inputChannel),
+          title,
+        }),
+      );
+    });
+  } else {
+    await mtprotoService.withFloodWaitHandling(async () => {
+      await client.invoke(
+        new Api.messages.EditChatTitle({
+          chatId: bigInt(chat.id),
+          title,
+        }),
+      );
+    });
+  }
+
+  return { data: undefined as unknown as void, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/editMessage.ts b/src/lib/mcp/telegram/api/editMessage.ts
new file mode 100644
index 000000000..337157b11
--- /dev/null
+++ b/src/lib/mcp/telegram/api/editMessage.ts
@@ -0,0 +1,29 @@
+/**
+ * API: Edit message
+ */
+
+import { mtprotoService } from "../../../../services/mtprotoService";
+import { getChatById } from "./helpers";
+import type { ApiResult } from "./types";
+
+export async function editMessage(
+  chatId: string | number,
+  messageId: number,
+  newText: string,
+): Promise<ApiResult<void>> {
+  const chat = getChatById(chatId);
+  if (!chat) {
+    throw new Error(`Chat not found: ${chatId}`);
+  }
+
+  const entity = chat.username
+    ? `@${chat.username.replace("@", "")}`
+    : chat.id;
+  const client = mtprotoService.getClient();
+
+  await mtprotoService.withFloodWaitHandling(async () => {
+    await client.editMessage(entity, { message: messageId, text: newText });
+  });
+
+  return { data: undefined as unknown as void, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/exportChatInvite.ts b/src/lib/mcp/telegram/api/exportChatInvite.ts
new file mode 100644
index 000000000..d295f08db
--- /dev/null
+++ b/src/lib/mcp/telegram/api/exportChatInvite.ts
@@ -0,0 +1,38 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import { getChatById } from "./helpers";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import type { ChatInviteResult } from "./apiResultTypes";
+import { narrow } from "./apiCastHelpers";
+
+export async function exportChatInvite(
+  chatId: string | number,
+  title?: string,
+  expireDate?: number,
+  usageLimit?: number,
+): Promise<ApiResult<{ link: string }>> {
+  const chat = getChatById(chatId);
+  if (!chat) throw new Error(`Chat not found: ${chatId}`);
+
+  const client = mtprotoService.getClient();
+  const entity = chat.username ? chat.username : chat.id;
+
+  const result = await mtprotoService.withFloodWaitHandling(async () => {
+    const inputPeer = await client.getInputEntity(entity);
+    return client.invoke(
+      new Api.messages.ExportChatInvite({
+        peer: inputPeer,
+        title: title ?? undefined,
+        expireDate: expireDate ?? undefined,
+        usageLimit: usageLimit ?? undefined,
+      }),
+    );
+  });
+
+  const link = narrow<ChatInviteResult>(result)?.link;
+  if (!link) {
+    throw new Error("Could not create invite link.");
+  }
+
+  return { data: { link }, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/exportContacts.ts b/src/lib/mcp/telegram/api/exportContacts.ts
new file mode 100644
index 000000000..f28afa42f
--- /dev/null
+++ b/src/lib/mcp/telegram/api/exportContacts.ts
@@ -0,0 +1,42 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import bigInt from "big-integer";
+import type { ApiUser } from "./apiResultTypes";
+
+export interface ExportedContact {
+  id: string;
+  firstName: string;
+  lastName: string;
+  username: string;
+  phone: string;
+}
+
+export async function exportContacts(): Promise<
+  ApiResult<ExportedContact[]>
+> {
+  const client = mtprotoService.getClient();
+
+  const result = await mtprotoService.withFloodWaitHandling(async () => {
+    return client.invoke(new Api.contacts.GetContacts({ hash: bigInt(0) }));
+  });
+
+  if (
+    !result ||
+    !("users" in result) ||
+    !Array.isArray(result.users) ||
+    result.users.length === 0
+  ) {
+    return { data: [], fromCache: false };
+  }
+
+  const contacts: ExportedContact[] = result.users.map((u: ApiUser) => ({
+    id: String(u.id),
+    firstName: u.firstName ?? "",
+    lastName: u.lastName ?? "",
+    username: u.username ?? "",
+    phone: u.phone ?? "",
+  }));
+
+  return { data: contacts, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/forwardMessage.ts b/src/lib/mcp/telegram/api/forwardMessage.ts
new file mode 100644
index 000000000..bfbfc939b
--- /dev/null
+++ b/src/lib/mcp/telegram/api/forwardMessage.ts
@@ -0,0 +1,40 @@
+/**
+ * API: Forward message
+ */
+
+import { mtprotoService } from "../../../../services/mtprotoService";
+import { getChatById } from "./helpers";
+import type { ApiResult } from "./types";
+
+export async function forwardMessage(
+  fromChatId: string | number,
+  toChatId: string | number,
+  messageId: number,
+): Promise<ApiResult<void>> {
+  const fromChat = getChatById(fromChatId);
+  if (!fromChat) {
+    throw new Error(`Source chat not found: ${fromChatId}`);
+  }
+
+  const toChat = getChatById(toChatId);
+  if (!toChat) {
+    throw new Error(`Target chat not found: ${toChatId}`);
+  }
+
+  const fromEntity = fromChat.username
+    ? `@${fromChat.username.replace("@", "")}`
+    : fromChat.id;
+  const toEntity = toChat.username
+    ? `@${toChat.username.replace("@", "")}`
+    : toChat.id;
+  const client = mtprotoService.getClient();
+
+  await mtprotoService.withFloodWaitHandling(async () => {
+    await client.forwardMessages(toEntity, {
+      messages: [messageId],
+      fromPeer: fromEntity,
+    });
+  });
+
+  return { data: undefined as unknown as void, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/getAdmins.ts b/src/lib/mcp/telegram/api/getAdmins.ts
new file mode 100644
index 000000000..fdce3cc01
--- /dev/null
+++ b/src/lib/mcp/telegram/api/getAdmins.ts
@@ -0,0 +1,60 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import bigInt from "big-integer";
+import type { ApiUser } from "./apiResultTypes";
+import { toInputChannel, narrow } from "./apiCastHelpers";
+import { getChatById } from "./helpers";
+
+export interface Admin {
+  id: string;
+  name: string;
+  username?: string;
+}
+
+export async function getAdmins(chatId: string | number): Promise<ApiResult<Admin[]>> {
+  const chat = getChatById(chatId);
+  if (!chat) {
+    throw new Error(`Chat not found: ${chatId}`);
+  }
+
+  const client = mtprotoService.getClient();
+  const entity = chat.username ? chat.username : chat.id;
+
+  let admins: ApiUser[] = [];
+
+  if (chat.type === "channel" || chat.type === "supergroup") {
+    const result = await mtprotoService.withFloodWaitHandling(async () => {
+      const inputChannel = await client.getInputEntity(entity);
+      return client.invoke(
+        new Api.channels.GetParticipants({
+          channel: toInputChannel(inputChannel),
+          filter: new Api.ChannelParticipantsAdmins(),
+          offset: 0,
+          limit: 100,
+          hash: bigInt(0),
+        }),
+      );
+    });
+    if (result && "users" in result && Array.isArray(result.users)) {
+      admins = narrow<ApiUser[]>(result.users);
+    }
+  } else {
+    const result = await mtprotoService.withFloodWaitHandling(async () => {
+      return client.invoke(
+        new Api.messages.GetFullChat({ chatId: bigInt(chat.id) }),
+      );
+    });
+    if (result && "users" in result && Array.isArray(result.users)) {
+      admins = narrow<ApiUser[]>(result.users);
+    }
+  }
+
+  const data: Admin[] = admins.map((u: ApiUser) => ({
+    id: String(u.id),
+    name: [u.firstName, u.lastName].filter(Boolean).join(" ") || "Unknown",
+    username: u.username,
+  }));
+
+  return { data, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/getBannedUsers.ts b/src/lib/mcp/telegram/api/getBannedUsers.ts
new file mode 100644
index 000000000..a33200447
--- /dev/null
+++ b/src/lib/mcp/telegram/api/getBannedUsers.ts
@@ -0,0 +1,62 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import bigInt from "big-integer";
+import type { ApiUser } from "./apiResultTypes";
+import { toInputChannel } from "./apiCastHelpers";
+import { getChatById } from "./helpers";
+
+export interface BannedUser {
+  id: string;
+  name: string;
+  username?: string;
+}
+
+export async function getBannedUsers(
+  chatId: string | number,
+  limit: number = 50,
+): Promise<ApiResult<BannedUser[]>> {
+  const chat = getChatById(chatId);
+  if (!chat) {
+    throw new Error(`Chat not found: ${chatId}`);
+  }
+
+  if (chat.type !== "channel" && chat.type !== "supergroup") {
+    throw new Error(
+      "Banned users list is only available for channels/supergroups.",
+    );
+  }
+
+  const client = mtprotoService.getClient();
+  const entity = chat.username ? chat.username : chat.id;
+
+  const result = await mtprotoService.withFloodWaitHandling(async () => {
+    const inputChannel = await client.getInputEntity(entity);
+    return client.invoke(
+      new Api.channels.GetParticipants({
+        channel: toInputChannel(inputChannel),
+        filter: new Api.ChannelParticipantsKicked({ q: "" }),
+        offset: 0,
+        limit,
+        hash: bigInt(0),
+      }),
+    );
+  });
+
+  if (
+    !result ||
+    !("users" in result) ||
+    !Array.isArray(result.users) ||
+    result.users.length === 0
+  ) {
+    return { data: [], fromCache: false };
+  }
+
+  const data: BannedUser[] = result.users.map((u: ApiUser) => ({
+    id: String(u.id),
+    name: [u.firstName, u.lastName].filter(Boolean).join(" ") || "Unknown",
+    username: u.username,
+  }));
+
+  return { data, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/getBlockedUsers.ts b/src/lib/mcp/telegram/api/getBlockedUsers.ts
new file mode 100644
index 000000000..bcbfa8724
--- /dev/null
+++ b/src/lib/mcp/telegram/api/getBlockedUsers.ts
@@ -0,0 +1,37 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import type { ApiUser } from "./apiResultTypes";
+
+export interface BlockedUser {
+  id: string;
+  name: string;
+  username?: string;
+}
+
+export async function getBlockedUsers(
+  limit: number = 50,
+): Promise<ApiResult<BlockedUser[]>> {
+  const client = mtprotoService.getClient();
+
+  const result = await mtprotoService.withFloodWaitHandling(async () => {
+    return client.invoke(new Api.contacts.GetBlocked({ offset: 0, limit }));
+  });
+
+  if (
+    !result ||
+    !("users" in result) ||
+    !Array.isArray(result.users) ||
+    result.users.length === 0
+  ) {
+    return { data: [], fromCache: false };
+  }
+
+  const blockedUsers: BlockedUser[] = result.users.map((u: ApiUser) => ({
+    id: String(u.id),
+    name: [u.firstName, u.lastName].filter(Boolean).join(" ") || "Unknown",
+    username: u.username,
+  }));
+
+  return { data: blockedUsers, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/getBotInfo.ts b/src/lib/mcp/telegram/api/getBotInfo.ts
new file mode 100644
index 000000000..b36653cce
--- /dev/null
+++ b/src/lib/mcp/telegram/api/getBotInfo.ts
@@ -0,0 +1,51 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import type { FullUserResult } from "./apiResultTypes";
+import { toInputUser, narrow } from "./apiCastHelpers";
+
+export interface BotInfo {
+  name: string;
+  username: string;
+  id: string;
+  isBot: boolean;
+  about?: string;
+  botDescription?: string;
+  commands?: Array<{ command: string; description: string }>;
+}
+
+export async function getBotInfo(
+  botId: string | number,
+): Promise<ApiResult<BotInfo>> {
+  const client = mtprotoService.getClient();
+
+  const result = await mtprotoService.withFloodWaitHandling(async () => {
+    const inputUser = await client.getInputEntity(botId);
+    return client.invoke(
+      new Api.users.GetFullUser({ id: toInputUser(inputUser) }),
+    );
+  });
+
+  const fullUser = narrow<FullUserResult>(result)?.fullUser;
+  const user = narrow<FullUserResult>(result)?.users?.[0];
+
+  if (!user) {
+    throw new Error("Bot not found: " + botId);
+  }
+
+  const name =
+    [user.firstName, user.lastName].filter(Boolean).join(" ") || "Unknown";
+
+  return {
+    data: {
+      name,
+      username: user.username ?? "N/A",
+      id: String(user.id),
+      isBot: user.bot ?? false,
+      about: fullUser?.about,
+      botDescription: fullUser?.botInfo?.description,
+      commands: fullUser?.botInfo?.commands,
+    },
+    fromCache: false,
+  };
+}
diff --git a/src/lib/mcp/telegram/api/getChat.ts b/src/lib/mcp/telegram/api/getChat.ts
new file mode 100644
index 000000000..47cd2aa73
--- /dev/null
+++ b/src/lib/mcp/telegram/api/getChat.ts
@@ -0,0 +1,111 @@
+/**
+ * API: Get chat — cache-first with API fallback (hybrid).
+ */
+
+import { mtprotoService } from "../../../../services/mtprotoService";
+import { enforceRateLimit } from "../../rateLimiter";
+import { getChatById, formatEntity } from "./helpers";
+import type { ApiResult } from "./types";
+
+export interface ChatInfo {
+  id: string;
+  name: string;
+  type: string;
+  username?: string;
+  participantsCount?: number;
+  unreadCount?: number;
+  phone?: string;
+  isBot?: boolean;
+  lastMessage?: {
+    from: string;
+    date: string;
+    text: string;
+  };
+}
+
+export async function getChat(
+  chatId: string | number,
+): Promise<ApiResult<ChatInfo | undefined>> {
+  // 1. Try cache
+  const chat = getChatById(chatId);
+  if (chat) {
+    const entity = formatEntity(chat);
+    const info: ChatInfo = {
+      id: entity.id,
+      name: entity.name,
+      type: entity.type,
+      username: entity.username,
+    };
+    if ("participantsCount" in chat && chat.participantsCount) {
+      info.participantsCount = chat.participantsCount as number;
+    }
+    if ("unreadCount" in chat) {
+      info.unreadCount = (chat.unreadCount as number) ?? 0;
+    }
+    const lastMsg = (
+      chat as {
+        lastMessage?: {
+          fromName?: string;
+          fromId?: string;
+          date: number;
+          message?: string;
+        };
+      }
+    ).lastMessage;
+    if (lastMsg) {
+      info.lastMessage = {
+        from: lastMsg.fromName ?? lastMsg.fromId ?? "Unknown",
+        date: new Date(lastMsg.date * 1000).toISOString(),
+        text: lastMsg.message || "[Media/No text]",
+      };
+    }
+    return { data: info, fromCache: true };
+  }
+
+  // 2. Cache miss — try Telegram API
+  try {
+    await enforceRateLimit("__api_fallback_chat");
+
+    const client = mtprotoService.getClient();
+    const rawEntity = await mtprotoService.withFloodWaitHandling(async () => {
+      return client.getEntity(chatId);
+    });
+
+    if (!rawEntity) return { data: undefined, fromCache: false };
+
+    const raw = rawEntity as unknown as Record<string, unknown>;
+    const className = raw.className as string | undefined;
+    const info: ChatInfo = {
+      id: String(raw.id ?? chatId),
+      name: "Unknown",
+      type: "unknown",
+    };
+
+    if (className === "User") {
+      info.name =
+        [raw.firstName, raw.lastName].filter(Boolean).join(" ") || "Unknown";
+      info.type = "user";
+      if (raw.username) info.username = String(raw.username);
+      if (raw.phone) info.phone = String(raw.phone);
+      if (raw.bot) info.isBot = true;
+    } else if (className === "Channel") {
+      info.name = (raw.title as string) ?? "Unknown";
+      info.type = raw.megagroup ? "supergroup" : "channel";
+      if (raw.username) info.username = String(raw.username);
+      if (raw.participantsCount)
+        info.participantsCount = raw.participantsCount as number;
+    } else if (className === "Chat") {
+      info.name = (raw.title as string) ?? "Unknown";
+      info.type = "group";
+      if (raw.participantsCount)
+        info.participantsCount = raw.participantsCount as number;
+    } else {
+      info.name =
+        (raw.title as string) ?? (raw.firstName as string) ?? "Unknown";
+    }
+
+    return { data: info, fromCache: false };
+  } catch {
+    return { data: undefined, fromCache: false };
+  }
+}
diff --git a/src/lib/mcp/telegram/api/getChats.ts b/src/lib/mcp/telegram/api/getChats.ts
new file mode 100644
index 000000000..1b867d864
--- /dev/null
+++ b/src/lib/mcp/telegram/api/getChats.ts
@@ -0,0 +1,70 @@
+/**
+ * API: Get chats — cache-first with API fallback.
+ */
+
+import type { TelegramChat } from "../../../../store/telegram/types";
+import { mtprotoService } from "../../../../services/mtprotoService";
+import { Api } from "telegram";
+import bigInt from "big-integer";
+import { enforceRateLimit } from "../../rateLimiter";
+import { getOrderedChats, apiDialogToTelegramChat } from "./helpers";
+import type { ApiResult } from "./types";
+
+export async function getChats(
+  limit = 20,
+): Promise<ApiResult<TelegramChat[]>> {
+  // 1. Try cache
+  const cached = getOrderedChats(limit);
+  if (cached.length > 0) return { data: cached, fromCache: true };
+
+  // 2. Rate limit before API call
+  try {
+    await enforceRateLimit("__api_fallback_chats");
+  } catch {
+    return { data: [], fromCache: false };
+  }
+
+  // 3. Fetch from Telegram API
+  try {
+    const client = mtprotoService.getClient();
+
+    const result = await mtprotoService.withFloodWaitHandling(async () => {
+      return client.invoke(
+        new Api.messages.GetDialogs({
+          offsetDate: 0,
+          offsetId: 0,
+          offsetPeer: new Api.InputPeerEmpty(),
+          limit,
+          hash: bigInt(0),
+        }),
+      );
+    });
+
+    if (!("dialogs" in result) || !Array.isArray(result.dialogs)) {
+      return { data: [], fromCache: false };
+    }
+
+    // Index chats and users by ID
+    const chatsById = new Map<string, Record<string, unknown>>();
+    const usersById = new Map<string, Record<string, unknown>>();
+    if ("chats" in result && Array.isArray(result.chats)) {
+      for (const c of result.chats as unknown as Record<string, unknown>[]) {
+        if (c.id != null) chatsById.set(String(c.id), c);
+      }
+    }
+    if ("users" in result && Array.isArray(result.users)) {
+      for (const u of result.users as unknown as Record<string, unknown>[]) {
+        if (u.id != null) usersById.set(String(u.id), u);
+      }
+    }
+
+    const data = (result.dialogs as unknown as Record<string, unknown>[])
+      .map((d) => apiDialogToTelegramChat(d, chatsById, usersById))
+      .filter((c): c is TelegramChat => c !== undefined)
+      .slice(0, limit);
+
+    return { data, fromCache: false };
+  } catch {
+    return { data: [], fromCache: false };
+  }
+}
diff --git a/src/lib/mcp/telegram/api/getContactChats.ts b/src/lib/mcp/telegram/api/getContactChats.ts
new file mode 100644
index 000000000..3d7317f9e
--- /dev/null
+++ b/src/lib/mcp/telegram/api/getContactChats.ts
@@ -0,0 +1,27 @@
+/**
+ * API: Get contact chats — cache-only.
+ */
+
+import { store } from "../../../../store";
+import { selectOrderedChats } from "../../../../store/telegramSelectors";
+import type { ApiResult } from "./types";
+
+export interface ContactChat {
+  id: string;
+  title: string;
+  username?: string;
+}
+
+export async function getContactChats(): Promise<ApiResult<ContactChat[]>> {
+  const state = store.getState();
+  const chats = selectOrderedChats(state);
+  const dmChats = chats
+    .filter((c) => c.type === "private")
+    .map((c) => ({
+      id: c.id,
+      title: c.title ?? "DM",
+      username: c.username,
+    }));
+
+  return { data: dmChats, fromCache: true };
+}
diff --git a/src/lib/mcp/telegram/api/getContactIds.ts b/src/lib/mcp/telegram/api/getContactIds.ts
new file mode 100644
index 000000000..bbe60bf2a
--- /dev/null
+++ b/src/lib/mcp/telegram/api/getContactIds.ts
@@ -0,0 +1,26 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import bigInt from "big-integer";
+import type { ContactIdEntry } from "./apiResultTypes";
+import { narrow } from "./apiCastHelpers";
+
+type ContactIdResult = number | ContactIdEntry;
+
+export async function getContactIds(): Promise<ApiResult<string[]>> {
+  const client = mtprotoService.getClient();
+
+  const result = await mtprotoService.withFloodWaitHandling(async () => {
+    return client.invoke(new Api.contacts.GetContactIDs({ hash: bigInt(0) }));
+  });
+
+  if (!result || !Array.isArray(result) || result.length === 0) {
+    return { data: [], fromCache: false };
+  }
+
+  const ids = narrow<ContactIdResult[]>(result).map((c) =>
+    String(typeof c === "number" ? c : (c.userId ?? c)),
+  );
+
+  return { data: ids, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/getCurrentUser.ts b/src/lib/mcp/telegram/api/getCurrentUser.ts
new file mode 100644
index 000000000..c58584b3a
--- /dev/null
+++ b/src/lib/mcp/telegram/api/getCurrentUser.ts
@@ -0,0 +1,57 @@
+/**
+ * API: Get current user — cache-first with API fallback.
+ */
+
+import type { TelegramUser } from "../../../../store/telegram/types";
+import { mtprotoService } from "../../../../services/mtprotoService";
+import { enforceRateLimit } from "../../rateLimiter";
+import { getCurrentUser as getCachedCurrentUser } from "./helpers";
+import type { ApiResult } from "./types";
+
+export async function getCurrentUser(): Promise<
+  ApiResult<TelegramUser | undefined>
+> {
+  // 1. Try cache
+  const cached = getCachedCurrentUser();
+  if (cached) return { data: cached, fromCache: true };
+
+  // 2. Rate limit before API call
+  try {
+    await enforceRateLimit("__api_fallback_me");
+  } catch {
+    return { data: undefined, fromCache: false };
+  }
+
+  // 3. Fetch from Telegram API
+  try {
+    const client = mtprotoService.getClient();
+    const me = await mtprotoService.withFloodWaitHandling(async () => {
+      return client.getMe();
+    });
+
+    if (!me) return { data: undefined, fromCache: false };
+
+    const raw = me as unknown as {
+      id?: unknown;
+      firstName?: string;
+      lastName?: string;
+      username?: string;
+      phone?: string;
+      bot?: boolean;
+    };
+
+    return {
+      data: {
+        id: String(raw.id ?? ""),
+        firstName: raw.firstName ?? "",
+        lastName: raw.lastName,
+        username: raw.username,
+        phoneNumber: raw.phone,
+        isBot: Boolean(raw.bot),
+      },
+      fromCache: false,
+    };
+  } catch {
+    return { data: undefined, fromCache: false };
+  }
+}
diff --git a/src/lib/mcp/telegram/api/getDirectChatByContact.ts b/src/lib/mcp/telegram/api/getDirectChatByContact.ts
new file mode 100644
index 000000000..5b606ad0b
--- /dev/null
+++ b/src/lib/mcp/telegram/api/getDirectChatByContact.ts
@@ -0,0 +1,35 @@
+/**
+ * API: Get direct chat by contact — cache-only.
+ */
+
+import { store } from "../../../../store";
+import { selectOrderedChats } from "../../../../store/telegramSelectors";
+import type { ApiResult } from "./types";
+
+export interface DirectChat {
+  id: string;
+  title: string;
+  username?: string;
+}
+
+export async function getDirectChatByContact(
+  userId: string | number,
+): Promise<ApiResult<DirectChat | undefined>> {
+  const state = store.getState();
+  const chats = selectOrderedChats(state);
+
+  const dmChat = chats.find(
+    (c) => c.type === "private" && String(c.id) === String(userId),
+  );
+
+  if (!dmChat) return { data: undefined, fromCache: true };
+
+  return {
+    data: {
+      id: dmChat.id,
+      title: dmChat.title ?? "DM",
+      username: dmChat.username,
+    },
+    fromCache: true,
+  };
+}
diff --git a/src/lib/mcp/telegram/api/getDrafts.ts b/src/lib/mcp/telegram/api/getDrafts.ts
new file mode 100644
index 000000000..442fde818
--- /dev/null
+++ b/src/lib/mcp/telegram/api/getDrafts.ts
@@ -0,0 +1,44 @@
+/**
+ * API: Get all drafts
+ */
+
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import type { UpdatesResult } from "./apiResultTypes";
+import { Api } from "telegram";
+import { narrow } from "./apiCastHelpers";
+
+export interface DraftData {
+  peerId: string;
+  message: string;
+}
+
+export async function getDrafts(): Promise<ApiResult<DraftData[]>> {
+  const client = mtprotoService.getClient();
+
+  const result = await mtprotoService.withFloodWaitHandling(async () => {
+    return client.invoke(new Api.messages.GetAllDrafts());
+  });
+
+  const updates = narrow<UpdatesResult>(result);
+  if (!updates || !updates.updates || updates.updates.length === 0) {
+    return { data: [], fromCache: false };
+  }
+
+  const drafts: DraftData[] = [];
+  for (const update of updates.updates) {
+    if (update.draft && update.draft.message) {
+      const peerId =
+        update.peer?.userId ??
+        update.peer?.chatId ??
+        update.peer?.channelId ??
+        "?";
+      drafts.push({
+        peerId: String(peerId),
+        message: update.draft.message,
+      });
+    }
+  }
+
+  return { data: drafts, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/getGifSearch.ts b/src/lib/mcp/telegram/api/getGifSearch.ts
new file mode 100644
index 000000000..c69472d9e
--- /dev/null
+++ b/src/lib/mcp/telegram/api/getGifSearch.ts
@@ -0,0 +1,47 @@
+/**
+ * Get GIF Search API - Search GIFs using Telegram's inline bot
+ *
+ * Uses the @gif bot to search for GIFs.
+ */
+
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import type { InlineBotResults } from "./apiResultTypes";
+import { toInputUser, narrow } from "./apiCastHelpers";
+import { Api } from "telegram";
+
+export interface GifResult {
+  title: string;
+  description?: string;
+}
+
+export async function getGifSearch(
+  query: string,
+  limit: number,
+): Promise<ApiResult<GifResult[]>> {
+  const client = mtprotoService.getClient();
+
+  const result = await mtprotoService.withFloodWaitHandling(async () => {
+    const bot = await client.getInputEntity("gif");
+    return client.invoke(
+      new Api.messages.GetInlineBotResults({
+        bot: toInputUser(bot),
+        peer: new Api.InputPeerSelf(),
+        query,
+        offset: "",
+      }),
+    );
+  });
+
+  const results = narrow<InlineBotResults>(result)?.results;
+  if (!results || !Array.isArray(results) || results.length === 0) {
+    return { data: [], fromCache: false };
+  }
+
+  const gifs: GifResult[] = results.slice(0, limit).map((r) => ({
+    title: r.title ?? r.description ?? "GIF",
+    description: r.description,
+  }));
+
+  return { data: gifs, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/getInviteLink.ts b/src/lib/mcp/telegram/api/getInviteLink.ts
new file mode 100644
index 000000000..bbffdec6f
--- /dev/null
+++ b/src/lib/mcp/telegram/api/getInviteLink.ts
@@ -0,0 +1,33 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import { getChatById } from "./helpers";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import type { ChatInviteResult } from "./apiResultTypes";
+import { narrow } from "./apiCastHelpers";
+
+export async function getInviteLink(
+  chatId: string | number,
+): Promise<ApiResult<{ link: string }>> {
+  const chat = getChatById(chatId);
+  if (!chat) throw new Error(`Chat not found: ${chatId}`);
+
+  const client = mtprotoService.getClient();
+  const entity = chat.username ? chat.username : chat.id;
+
+  const result = await mtprotoService.withFloodWaitHandling(async () => {
+    const inputPeer = await client.getInputEntity(entity);
+    return client.invoke(
+      new Api.messages.ExportChatInvite({
+        peer: inputPeer,
+        legacyRevokePermanent: true,
+      }),
+    );
+  });
+
+  const link = narrow<ChatInviteResult>(result)?.link;
+  if (!link) {
+    throw new Error("Could not generate invite link.");
+  }
+
+  return { data: { link }, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/getLastInteraction.ts b/src/lib/mcp/telegram/api/getLastInteraction.ts
new file mode 100644
index 000000000..1a61cfc9c
--- /dev/null
+++ b/src/lib/mcp/telegram/api/getLastInteraction.ts
@@ -0,0 +1,38 @@
+/**
+ * API: Get last interaction — cache-only.
+ */
+
+import type { ApiResult } from "./types";
+import { getChatById, getCachedMessages, formatMessage } from "./helpers";
+
+export interface LastInteraction {
+  chatTitle: string;
+  from: string;
+  date: string;
+  text: string;
+}
+
+export async function getLastInteraction(
+  chatId: string | number,
+): Promise<ApiResult<LastInteraction | undefined>> {
+  const chat = getChatById(chatId);
+  if (!chat) return { data: undefined, fromCache: true };
+
+  const messages = getCachedMessages(chatId, 1, 0);
+  if (!messages || messages.length === 0) {
+    return { data: undefined, fromCache: true };
+  }
+
+  const msg = messages[0];
+  const f = formatMessage(msg);
+
+  return {
+    data: {
+      chatTitle: chat.title ?? String(chatId),
+      from: msg.fromName ?? msg.fromId ?? "Unknown",
+      date: f.date,
+      text: f.text || "[Media/No text]",
+    },
+    fromCache: true,
+  };
+}
diff --git a/src/lib/mcp/telegram/api/getMediaInfo.ts b/src/lib/mcp/telegram/api/getMediaInfo.ts
new file mode 100644
index 000000000..3e577482a
--- /dev/null
+++ b/src/lib/mcp/telegram/api/getMediaInfo.ts
@@ -0,0 +1,47 @@
+/**
+ * Get Media Info API - Get media info from a cached message
+ *
+ * Reads from cached messages only, does not make API calls.
+ */
+
+import { getChatById, getCachedMessages } from "./helpers";
+import type { ApiResult } from "./types";
+
+export interface MediaInfo {
+  type: string;
+  [key: string]: unknown;
+}
+
+export async function getMediaInfo(
+  chatId: string | number,
+  messageId: number,
+): Promise<ApiResult<MediaInfo>> {
+  const chat = getChatById(chatId);
+  if (!chat) {
+    throw new Error("Chat not found: " + chatId);
+  }
+
+  const messages = getCachedMessages(chatId, 200, 0);
+  if (!messages || messages.length === 0) {
+    throw new Error("No messages found in cache.");
+  }
+
+  const msg = messages.find((m) => String(m.id) === String(messageId));
+  if (!msg) {
+    throw new Error("Message " + messageId + " not found in cache.");
+  }
+
+  if (!msg.media) {
+    return {
+      data: { type: "none" },
+      fromCache: true,
+    };
+  }
+
+  const info: MediaInfo = {
+    ...msg.media,
+    type: msg.media.type ?? "unknown",
+  };
+
+  return { data: info, fromCache: true };
+}
diff --git a/src/lib/mcp/telegram/api/getMessageReactions.ts b/src/lib/mcp/telegram/api/getMessageReactions.ts
new file mode 100644
index 000000000..9f88152da
--- /dev/null
+++ b/src/lib/mcp/telegram/api/getMessageReactions.ts
@@ -0,0 +1,58 @@
+/**
+ * API: Get message reactions
+ */
+
+import { mtprotoService } from "../../../../services/mtprotoService";
+import { getChatById } from "./helpers";
+import type { ApiResult } from "./types";
+import type { UpdatesResult } from "./apiResultTypes";
+import { Api } from "telegram";
+import { narrow } from "./apiCastHelpers";
+
+export interface ReactionData {
+  emoji: string;
+  count: number;
+}
+
+export async function getMessageReactions(
+  chatId: string | number,
+  messageId: number,
+): Promise<ApiResult<ReactionData[]>> {
+  const chat = getChatById(chatId);
+  if (!chat) {
+    throw new Error(`Chat not found: ${chatId}`);
+  }
+
+  const client = mtprotoService.getClient();
+  const entity = chat.username
+    ? `@${chat.username.replace("@", "")}`
+    : chat.id;
+
+  const result = await mtprotoService.withFloodWaitHandling(async () => {
+    const inputPeer = await client.getInputEntity(entity);
+    return client.invoke(
+      new Api.messages.GetMessagesReactions({
+        peer: inputPeer,
+        id: [messageId],
+      }),
+    );
+  });
+
+  const updates = narrow<UpdatesResult>(result);
+  if (!updates || !updates.updates || updates.updates.length === 0) {
+    return { data: [], fromCache: false };
+  }
+
+  const reactions: ReactionData[] = [];
+  for (const update of updates.updates) {
+    if (update.reactions && update.reactions.results) {
+      for (const r of update.reactions.results) {
+        const emoji = r.reaction?.emoticon ?? r.reaction?.className ?? "?";
+        const count = r.count ?? 0;
+        reactions.push({ emoji, count });
+      }
+    }
+  }
+
+  return { data: reactions, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/getMessages.ts b/src/lib/mcp/telegram/api/getMessages.ts
new file mode 100644
index 000000000..67abf5a73
--- /dev/null
+++ b/src/lib/mcp/telegram/api/getMessages.ts
@@ -0,0 +1,98 @@
+/**
+ * API: Get messages — cache-first with API fallback.
+ */
+
+import type { TelegramMessage } from "../../../../store/telegram/types";
+import { mtprotoService } from "../../../../services/mtprotoService";
+import { Api } from "telegram";
+import bigInt from "big-integer";
+import { enforceRateLimit } from "../../rateLimiter";
+import {
+  getChatById,
+  getCachedMessages,
+  apiMessageToTelegramMessage,
+} from "./helpers";
+import type { ApiResult } from "./types";
+
+export async function getMessages(
+  chatId: string | number,
+  limit = 20,
+  offset = 0,
+): Promise<ApiResult<TelegramMessage[]>> {
+  // 1. Try cache
+  const cached = getCachedMessages(chatId, limit, offset);
+  if (cached && cached.length > 0) {
+    return { data: cached, fromCache: true };
+  }
+
+  // 2. Resolve chat for API call
+  const chat = getChatById(chatId);
+  if (!chat) return { data: [], fromCache: false };
+
+  // 3. Rate limit before API call
+  try {
+    await enforceRateLimit("__api_fallback_messages");
+  } catch {
+    return { data: [], fromCache: false };
+  }
+
+  // 4. Fetch from Telegram API
+  try {
+    const client = mtprotoService.getClient();
+    const entity = chat.username ? chat.username : chat.id;
+    const inputPeer = await client.getInputEntity(entity);
+
+    const result = await mtprotoService.withFloodWaitHandling(async () => {
+      return client.invoke(
+        new Api.messages.GetHistory({
+          peer: inputPeer,
+          offsetId: 0,
+          offsetDate: 0,
+          addOffset: offset,
+          limit,
+          maxId: 0,
+          minId: 0,
+          hash: bigInt(0),
+        }),
+      );
+    });
+
+    if ("messages" in result && Array.isArray(result.messages)) {
+      const messages = (
+        result.messages as unknown as Record<string, unknown>[]
+      )
+        .filter((m) => m.className !== "MessageEmpty")
+        .map((m) => apiMessageToTelegramMessage(m, chat.id));
+
+      // Enrich fromName from users list
+      if ("users" in result && Array.isArray(result.users)) {
+        const usersById = new Map<string, string>();
+        for (const u of result.users as Array<{
+          id?: unknown;
+          firstName?: string;
+          lastName?: string;
+        }>) {
+          if (u.id != null) {
+            const name =
+              [u.firstName, u.lastName].filter(Boolean).join(" ") || "Unknown";
+            usersById.set(String(u.id), name);
+          }
+        }
+        for (const msg of messages) {
+          if (msg.fromId && !msg.fromName) {
+            msg.fromName = usersById.get(msg.fromId);
+          }
+        }
+      }
+
+      return {
+        data: messages.length > 0 ? messages : [],
+        fromCache: false,
+      };
+    }
+  } catch {
+    // API failed — return empty
+  }
+
+  return { data: [], fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/getParticipants.ts b/src/lib/mcp/telegram/api/getParticipants.ts
new file mode 100644
index 000000000..bd7b9ffbc
--- /dev/null
+++ b/src/lib/mcp/telegram/api/getParticipants.ts
@@ -0,0 +1,63 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import bigInt from "big-integer";
+import type { ApiUser } from "./apiResultTypes";
+import { toInputChannel, narrow } from "./apiCastHelpers";
+import { getChatById } from "./helpers";
+
+export interface Participant {
+  id: string;
+  name: string;
+  username?: string;
+}
+
+export async function getParticipants(
+  chatId: string | number,
+  limit: number = 50,
+): Promise<ApiResult<Participant[]>> {
+  const chat = getChatById(chatId);
+  if (!chat) {
+    throw new Error(`Chat not found: ${chatId}`);
+  }
+
+  const client = mtprotoService.getClient();
+  const entity = chat.username ? chat.username : chat.id;
+
+  let participants: ApiUser[] = [];
+
+  if (chat.type === "channel" || chat.type === "supergroup") {
+    const result = await mtprotoService.withFloodWaitHandling(async () => {
+      const inputChannel = await client.getInputEntity(entity);
+      return client.invoke(
+        new Api.channels.GetParticipants({
+          channel: toInputChannel(inputChannel),
+          filter: new Api.ChannelParticipantsRecent(),
+          offset: 0,
+          limit,
+          hash: bigInt(0),
+        }),
+      );
+    });
+    if (result && "users" in result && Array.isArray(result.users)) {
+      participants = narrow<ApiUser[]>(result.users);
+    }
+  } else {
+    const result = await mtprotoService.withFloodWaitHandling(async () => {
+      return client.invoke(
+        new Api.messages.GetFullChat({ chatId: bigInt(chat.id) }),
+      );
+    });
+    if (result && "users" in result && Array.isArray(result.users)) {
+      participants = narrow<ApiUser[]>(result.users);
+    }
+  }
+
+  const data: Participant[] = participants.map((u: ApiUser) => ({
+    id: String(u.id),
+    name: [u.firstName, u.lastName].filter(Boolean).join(" ") || "Unknown",
+    username: u.username,
+  }));
+
+  return { data, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/getPinnedMessages.ts b/src/lib/mcp/telegram/api/getPinnedMessages.ts
new file mode 100644
index 000000000..cc41b0d06
--- /dev/null
+++ b/src/lib/mcp/telegram/api/getPinnedMessages.ts
@@ -0,0 +1,68 @@
+/**
+ * API: Get pinned messages (API-first with cache fallback)
+ */
+
+import { mtprotoService } from "../../../../services/mtprotoService";
+import { getChatById } from "./helpers";
+import type { ApiResult } from "./types";
+import type { ApiMessage } from "./apiResultTypes";
+import { Api } from "telegram";
+import bigInt from "big-integer";
+import { narrow } from "./apiCastHelpers";
+
+export interface PinnedMessage {
+  id: number | string;
+  date: string;
+  text: string;
+}
+
+export async function getPinnedMessages(
+  chatId: string | number,
+): Promise<ApiResult<PinnedMessage[]>> {
+  const chat = getChatById(chatId);
+  if (!chat) {
+    throw new Error(`Chat not found: ${chatId}`);
+  }
+
+  const entity = chat.username
+    ? `@${chat.username.replace("@", "")}`
+    : chat.id;
+  const client = mtprotoService.getClient();
+
+  // Try API first
+  try {
+    const inputPeer = await client.getInputEntity(entity);
+    const result = await client.invoke(
+      new Api.messages.Search({
+        peer: inputPeer,
+        q: "",
+        filter: new Api.InputMessagesFilterPinned(),
+        minDate: 0,
+        maxDate: 0,
+        offsetId: 0,
+        addOffset: 0,
+        limit: 50,
+        maxId: 0,
+        minId: 0,
+        hash: bigInt(0),
+      }),
+    );
+
+    if ("messages" in result && Array.isArray(result.messages)) {
+      const pinnedMessages = narrow<ApiMessage[]>(result.messages).map((msg) => ({
+        id: msg.id ?? "?",
+        date: msg.date
+          ? new Date(msg.date * 1000).toISOString()
+          : "unknown",
+        text: msg.message ?? "[Media/No text]",
+      }));
+      return { data: pinnedMessages, fromCache: false };
+    }
+  } catch {
+    // API failed, fall back to cache below
+  }
+
+  // Fallback: pinned status is not stored in Redux cache (TelegramMessage),
+  // so we can't provide pinned messages from cache. Return empty result.
+  return { data: [], fromCache: true };
+}
diff --git a/src/lib/mcp/telegram/api/getPrivacySettings.ts b/src/lib/mcp/telegram/api/getPrivacySettings.ts
new file mode 100644
index 000000000..407e8722e
--- /dev/null
+++ b/src/lib/mcp/telegram/api/getPrivacySettings.ts
@@ -0,0 +1,62 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import type { PrivacyResult } from "./apiResultTypes";
+import { narrow } from "./apiCastHelpers";
+
+export type PrivacyKey =
+  | "phone_number"
+  | "last_seen"
+  | "profile_photo"
+  | "forwards"
+  | "phone_call"
+  | "chat_invite";
+
+export interface PrivacySettings {
+  key: PrivacyKey;
+  rules: string[];
+}
+
+const keyMap: Record<PrivacyKey, Api.TypeInputPrivacyKey> = {
+  phone_number: new Api.InputPrivacyKeyPhoneNumber(),
+  last_seen: new Api.InputPrivacyKeyStatusTimestamp(),
+  profile_photo: new Api.InputPrivacyKeyProfilePhoto(),
+  forwards: new Api.InputPrivacyKeyForwards(),
+  phone_call: new Api.InputPrivacyKeyPhoneCall(),
+  chat_invite: new Api.InputPrivacyKeyChatInvite(),
+};
+
+export async function getPrivacySettings(
+  key: string = "last_seen",
+): Promise<ApiResult<PrivacySettings>> {
+  if (!(key in keyMap)) {
+    throw new Error(
+      "Unknown privacy key: " +
+        key +
+        ". Valid keys: " +
+        Object.keys(keyMap).join(", "),
+    );
+  }
+
+  const privacyKey = key as PrivacyKey;
+  const client = mtprotoService.getClient();
+
+  const result = await mtprotoService.withFloodWaitHandling(async () => {
+    return client.invoke(new Api.account.GetPrivacy({ key: keyMap[privacyKey] }));
+  });
+
+  const rules = narrow<PrivacyResult>(result)?.rules;
+  if (!rules || !Array.isArray(rules)) {
+    return {
+      data: { key: privacyKey, rules: [] },
+      fromCache: false,
+    };
+  }
+
+  const ruleNames = rules.map((r) => r.className ?? "Unknown rule");
+
+  return {
+    data: { key: privacyKey, rules: ruleNames },
+    fromCache: false,
+  };
+}
diff --git a/src/lib/mcp/telegram/api/getRecentActions.ts b/src/lib/mcp/telegram/api/getRecentActions.ts
new file mode 100644
index 000000000..8421017c7
--- /dev/null
+++ b/src/lib/mcp/telegram/api/getRecentActions.ts
@@ -0,0 +1,63 @@
+/**
+ * Get Recent Actions API - Get recent admin actions in a chat
+ *
+ * Fetches admin log from channels/supergroups only.
+ */
+
+import { mtprotoService } from "../../../../services/mtprotoService";
+import { getChatById } from "./helpers";
+import type { ApiResult } from "./types";
+import type { AdminLogResult } from "./apiResultTypes";
+import { toInputChannel, narrow } from "./apiCastHelpers";
+import { Api } from "telegram";
+import bigInt from "big-integer";
+
+export interface AdminActionResult {
+  date: string;
+  action: string;
+}
+
+export async function getRecentActions(
+  chatId: string | number,
+  limit: number,
+): Promise<ApiResult<AdminActionResult[]>> {
+  const chat = getChatById(chatId);
+  if (!chat) {
+    throw new Error("Chat not found: " + chatId);
+  }
+
+  if (chat.type !== "channel" && chat.type !== "supergroup") {
+    throw new Error(
+      "Recent actions are only available for channels/supergroups.",
+    );
+  }
+
+  const client = mtprotoService.getClient();
+  const entity = chat.username ? chat.username : chat.id;
+
+  const result = await mtprotoService.withFloodWaitHandling(async () => {
+    const inputChannel = await client.getInputEntity(entity);
+    return client.invoke(
+      new Api.channels.GetAdminLog({
+        channel: toInputChannel(inputChannel),
+        q: "",
+        maxId: bigInt(0),
+        minId: bigInt(0),
+        limit,
+      }),
+    );
+  });
+
+  const events = narrow<AdminLogResult>(result)?.events;
+  if (!events || !Array.isArray(events) || events.length === 0) {
+    return { data: [], fromCache: false };
+  }
+
+  const actions: AdminActionResult[] = events.map((e) => {
+    const date = e.date ? new Date(e.date * 1000).toISOString() : "unknown";
+    const action = e.action?.className ?? "unknown";
+    return { date, action };
+  });
+
+  return { data: actions, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/getStickerSets.ts b/src/lib/mcp/telegram/api/getStickerSets.ts
new file mode 100644
index 000000000..9c33504ff
--- /dev/null
+++ b/src/lib/mcp/telegram/api/getStickerSets.ts
@@ -0,0 +1,41 @@
+/**
+ * Get Sticker Sets API - Get user's sticker sets
+ *
+ * Fetches all available sticker sets for the current user.
+ */
+
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import type { StickerSetsResult } from "./apiResultTypes";
+import { narrow } from "./apiCastHelpers";
+import { Api } from "telegram";
+import bigInt from "big-integer";
+
+export interface StickerSetResult {
+  id: string;
+  title: string;
+  count: number;
+}
+
+export async function getStickerSets(): Promise<
+  ApiResult<StickerSetResult[]>
+> {
+  const client = mtprotoService.getClient();
+
+  const result = await mtprotoService.withFloodWaitHandling(async () => {
+    return client.invoke(new Api.messages.GetAllStickers({ hash: bigInt(0) }));
+  });
+
+  const sets = narrow<StickerSetsResult>(result)?.sets;
+  if (!sets || !Array.isArray(sets) || sets.length === 0) {
+    return { data: [], fromCache: false };
+  }
+
+  const stickerSets: StickerSetResult[] = sets.map((s) => ({
+    id: String(s.id),
+    title: s.title ?? "Untitled",
+    count: s.count ?? 0,
+  }));
+
+  return { data: stickerSets, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/getUserPhotos.ts b/src/lib/mcp/telegram/api/getUserPhotos.ts
new file mode 100644
index 000000000..80919708f
--- /dev/null
+++ b/src/lib/mcp/telegram/api/getUserPhotos.ts
@@ -0,0 +1,48 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import bigInt from "big-integer";
+import type { ApiPhoto } from "./apiResultTypes";
+import { toInputUser, narrow } from "./apiCastHelpers";
+
+export interface UserPhoto {
+  id: string;
+  date: string;
+}
+
+export async function getUserPhotos(
+  userId: string | number,
+  limit: number = 10,
+): Promise<ApiResult<UserPhoto[]>> {
+  const client = mtprotoService.getClient();
+
+  const result = await mtprotoService.withFloodWaitHandling(async () => {
+    const inputUser = await client.getInputEntity(userId);
+    return client.invoke(
+      new Api.photos.GetUserPhotos({
+        userId: toInputUser(inputUser),
+        offset: 0,
+        maxId: bigInt(0),
+        limit,
+      }),
+    );
+  });
+
+  if (
+    !result ||
+    !("photos" in result) ||
+    !Array.isArray(result.photos) ||
+    result.photos.length === 0
+  ) {
+    return { data: [], fromCache: false };
+  }
+
+  const photos = narrow<ApiPhoto[]>(result.photos).map((photo) => ({
+    id: String(photo.id),
+    date: photo.date
+      ? new Date(photo.date * 1000).toISOString()
+      : "unknown",
+  }));
+
+  return { data: photos, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/getUserStatus.ts b/src/lib/mcp/telegram/api/getUserStatus.ts
new file mode 100644
index 000000000..fee211041
--- /dev/null
+++ b/src/lib/mcp/telegram/api/getUserStatus.ts
@@ -0,0 +1,66 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import type { ApiUser } from "./apiResultTypes";
+import { toInputUser, narrow } from "./apiCastHelpers";
+
+export interface UserStatus {
+  userId: string;
+  name: string;
+  status: string;
+  lastSeen?: string;
+}
+
+export async function getUserStatus(
+  userId: string | number,
+): Promise<ApiResult<UserStatus>> {
+  const client = mtprotoService.getClient();
+
+  const result = await mtprotoService.withFloodWaitHandling(async () => {
+    const inputUser = await client.getInputEntity(userId);
+    return client.invoke(
+      new Api.users.GetUsers({ id: [toInputUser(inputUser)] }),
+    );
+  });
+
+  if (!result || !Array.isArray(result) || result.length === 0) {
+    throw new Error("User " + userId + " not found.");
+  }
+
+  const user = narrow<ApiUser>(result[0]);
+  const name =
+    [user.firstName, user.lastName].filter(Boolean).join(" ") || "Unknown";
+  let statusText = "unknown";
+  let lastSeen: string | undefined = undefined;
+
+  if (user.status) {
+    const s = user.status;
+    if (s.className === "UserStatusOnline") {
+      statusText = "Online";
+    } else if (s.className === "UserStatusOffline") {
+      const lastSeenDate = s.wasOnline
+        ? new Date(s.wasOnline * 1000).toISOString()
+        : "unknown";
+      statusText = "Offline";
+      lastSeen = lastSeenDate;
+    } else if (s.className === "UserStatusRecently") {
+      statusText = "Recently";
+    } else if (s.className === "UserStatusLastWeek") {
+      statusText = "Last week";
+    } else if (s.className === "UserStatusLastMonth") {
+      statusText = "Last month";
+    } else {
+      statusText = s.className ?? "unknown";
+    }
+  }
+
+  return {
+    data: {
+      userId: String(user.id),
+      name,
+      status: statusText,
+      lastSeen,
+    },
+    fromCache: false,
+  };
+}
diff --git a/src/lib/mcp/telegram/api/helpers.ts b/src/lib/mcp/telegram/api/helpers.ts
new file mode 100644
index 000000000..071f588ad
--- /dev/null
+++ b/src/lib/mcp/telegram/api/helpers.ts
@@ -0,0 +1,292 @@
+/**
+ * Shared helpers for the Telegram API layer.
+ *
+ * Cache lookups, entity formatting, and message formatting live here.
+ * These are used by both api/ functions and (transitionally) by tool wrappers.
+ */
+
+import { store } from "../../../../store";
+import {
+  selectOrderedChats,
+  selectCurrentUser,
+  selectTelegramUserState,
+} from "../../../../store/telegramSelectors";
+import type {
+  TelegramChat,
+  TelegramUser,
+  TelegramMessage,
+} from "../../../../store/telegram/types";
+
+// ---------------------------------------------------------------------------
+// Redux state helpers
+// ---------------------------------------------------------------------------
+
+export function getTelegramState() {
+  return selectTelegramUserState(store.getState());
+}
+
+// ---------------------------------------------------------------------------
+// Cache lookups
+// ---------------------------------------------------------------------------
+
+/**
+ * Get chat by ID or username from Redux cache.
+ */
+export function getChatById(
+  chatId: string | number,
+): TelegramChat | undefined {
+  const state = getTelegramState();
+  const idStr = String(chatId);
+
+  const chat = state.chats[idStr];
+  if (chat) return chat;
+
+  if (
+    typeof chatId === "string" &&
+    (chatId.startsWith("@") || /^[a-zA-Z0-9_]+$/.test(chatId))
+  ) {
+    const username = chatId.startsWith("@") ? chatId : `@${chatId}`;
+    return Object.values(state.chats).find(
+      (c) =>
+        c.username &&
+        (c.username === username || c.username === username.slice(1)),
+    );
+  }
+
+  return undefined;
+}
+
+/**
+ * Get user by ID (current user only; no full user cache).
+ */
+export function getUserById(
+  userId: string | number,
+): TelegramUser | undefined {
+  const state = getTelegramState();
+  const current = state.currentUser;
+  if (!current) return undefined;
+  if (String(current.id) === String(userId)) return current;
+  return undefined;
+}
+
+/**
+ * Get current user from Redux cache.
+ */
+export function getCurrentUser(): TelegramUser | undefined {
+  const state = store.getState();
+  return selectCurrentUser(state) ?? undefined;
+}
+
+/**
+ * Get ordered chats from Redux cache.
+ */
+export function getOrderedChats(limit = 20): TelegramChat[] {
+  const state = store.getState();
+  const ordered = selectOrderedChats(state);
+  return ordered.slice(0, limit);
+}
+
+/**
+ * Get cached messages for a chat from Redux store.
+ */
+export function getCachedMessages(
+  chatId: string | number,
+  limit = 20,
+  offset = 0,
+): TelegramMessage[] | undefined {
+  const chat = getChatById(chatId);
+  if (!chat) return undefined;
+
+  const state = getTelegramState();
+  const order = state.messagesOrder[chat.id] ?? [];
+  const byId = state.messages[chat.id] ?? {};
+  const all = order.map((id) => byId[id]).filter(Boolean);
+  const list = all.slice(offset, offset + limit);
+
+  return list.length ? list : undefined;
+}
+
+/**
+ * Search chats by query (filter by title/username from cache).
+ */
+export function searchChatsInCache(query: string): TelegramChat[] {
+  const state = store.getState();
+  const ordered = selectOrderedChats(state);
+  const q = query.toLowerCase();
+  return ordered.filter((c) => {
+    const title = (c.title ?? "").toLowerCase();
+    const un = (c.username ?? "").toLowerCase();
+    return title.includes(q) || un.includes(q);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Formatting helpers
+// ---------------------------------------------------------------------------
+
+export interface FormattedEntity {
+  id: string;
+  name: string;
+  type: string;
+  username?: string;
+  phone?: string;
+}
+
+export interface FormattedMessage {
+  id: number | string;
+  date: string;
+  text: string;
+  from_id?: string;
+  has_media?: boolean;
+  media_type?: string;
+}
+
+/**
+ * Format entity (chat or user) for display.
+ */
+export function formatEntity(
+  entity: TelegramChat | TelegramUser,
+): FormattedEntity {
+  if ("title" in entity) {
+    const chat = entity as TelegramChat;
+    const type =
+      chat.type === "channel"
+        ? "channel"
+        : chat.type === "supergroup"
+          ? "group"
+          : chat.type;
+    return {
+      id: chat.id,
+      name: chat.title ?? "Unknown",
+      type,
+      username: chat.username,
+    };
+  }
+  const user = entity as TelegramUser;
+  const name =
+    [user.firstName, user.lastName].filter(Boolean).join(" ") || "Unknown";
+  return {
+    id: user.id,
+    name,
+    type: "user",
+    username: user.username,
+    phone: user.phoneNumber,
+  };
+}
+
+/**
+ * Format message for display.
+ */
+export function formatMessage(message: TelegramMessage): FormattedMessage {
+  const result: FormattedMessage = {
+    id: message.id,
+    date: new Date(message.date * 1000).toISOString(),
+    text: message.message ?? "",
+  };
+  if (message.fromId) result.from_id = message.fromId;
+  if (message.media?.type) {
+    result.has_media = true;
+    result.media_type = message.media.type;
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// GramJS conversion helpers (used by API fallback functions)
+// ---------------------------------------------------------------------------
+
+/** Convert a raw GramJS message to our TelegramMessage format */
+export function apiMessageToTelegramMessage(
+  msg: Record<string, unknown>,
+  chatId: string,
+): TelegramMessage {
+  const fromId =
+    msg.fromId &&
+    typeof msg.fromId === "object" &&
+    "userId" in (msg.fromId as object)
+      ? String((msg.fromId as { userId: unknown }).userId)
+      : undefined;
+
+  const replyTo = msg.replyTo as { replyToMsgId?: number } | undefined;
+
+  const media = msg.media as { className?: string } | undefined;
+  let mediaInfo: TelegramMessage["media"] | undefined;
+  if (media && media.className && media.className !== "MessageMediaEmpty") {
+    mediaInfo = { type: media.className };
+  }
+
+  return {
+    id: String(msg.id ?? ""),
+    chatId,
+    date: typeof msg.date === "number" ? msg.date : 0,
+    message: typeof msg.message === "string" ? msg.message : "",
+    fromId,
+    isOutgoing: Boolean(msg.out),
+    isEdited: msg.editDate != null,
+    isForwarded: msg.fwdFrom != null,
+    replyToMessageId:
+      replyTo?.replyToMsgId != null
+        ? String(replyTo.replyToMsgId)
+        : undefined,
+    media: mediaInfo,
+  };
+}
+
+/** Convert a raw GramJS dialog + chat/user to our TelegramChat format */
+export function apiDialogToTelegramChat(
+  dialog: Record<string, unknown>,
+  chatsById: Map<string, Record<string, unknown>>,
+  usersById: Map<string, Record<string, unknown>>,
+): TelegramChat | undefined {
+  const peer = dialog.peer as
+    | {
+        className?: string;
+        userId?: unknown;
+        chatId?: unknown;
+        channelId?: unknown;
+      }
+    | undefined;
+  if (!peer) return undefined;
+
+  let id: string;
+  let type: TelegramChat["type"];
+  let raw: Record<string, unknown> | undefined;
+
+  if (peer.className === "PeerUser" && peer.userId != null) {
+    id = String(peer.userId);
+    type = "private";
+    raw = usersById.get(id);
+  } else if (peer.className === "PeerChat" && peer.chatId != null) {
+    id = String(peer.chatId);
+    type = "group";
+    raw = chatsById.get(id);
+  } else if (peer.className === "PeerChannel" && peer.channelId != null) {
+    id = String(peer.channelId);
+    raw = chatsById.get(id);
+    type = raw && Boolean(raw.megagroup) ? "supergroup" : "channel";
+  } else {
+    return undefined;
+  }
+
+  let title: string;
+  let username: string | undefined;
+  if (raw) {
+    title =
+      (raw.title as string) ??
+      [raw.firstName, raw.lastName].filter(Boolean).join(" ") ??
+      "Unknown";
+    username = raw.username as string | undefined;
+  } else {
+    title = "Unknown";
+  }
+
+  return {
+    id,
+    title,
+    type,
+    username,
+    unreadCount:
+      typeof dialog.unreadCount === "number" ? dialog.unreadCount : 0,
+    isPinned: Boolean(dialog.pinned),
+  };
+}
diff --git a/src/lib/mcp/telegram/api/importChatInvite.ts b/src/lib/mcp/telegram/api/importChatInvite.ts
new file mode 100644
index 000000000..7aae33aa1
--- /dev/null
+++ b/src/lib/mcp/telegram/api/importChatInvite.ts
@@ -0,0 +1,20 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import type { ResultWithChats } from "./apiResultTypes";
+import { narrow } from "./apiCastHelpers";
+
+export async function importChatInvite(
+  hash: string,
+): Promise<ApiResult<{ chatTitle: string }>> {
+  const client = mtprotoService.getClient();
+
+  const result = await mtprotoService.withFloodWaitHandling(async () => {
+    return client.invoke(new Api.messages.ImportChatInvite({ hash }));
+  });
+
+  const chatTitle =
+    narrow<ResultWithChats>(result)?.chats?.[0]?.title ?? "unknown";
+
+  return { data: { chatTitle }, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/importContacts.ts b/src/lib/mcp/telegram/api/importContacts.ts
new file mode 100644
index 000000000..e6f831091
--- /dev/null
+++ b/src/lib/mcp/telegram/api/importContacts.ts
@@ -0,0 +1,44 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import bigInt from "big-integer";
+import type { ContactInput, ImportContactsResult } from "./apiResultTypes";
+import { narrow } from "./apiCastHelpers";
+
+export interface ImportContactsResponse {
+  imported: number;
+  total: number;
+}
+
+export async function importContacts(
+  contacts: ContactInput[],
+): Promise<ApiResult<ImportContactsResponse>> {
+  if (!Array.isArray(contacts) || contacts.length === 0) {
+    throw new Error("contacts array is required and must not be empty.");
+  }
+
+  const inputContacts = contacts.map(
+    (c: ContactInput, i: number) =>
+      new Api.InputPhoneContact({
+        clientId: bigInt(i),
+        phone: String(c.phone ?? ""),
+        firstName: String(c.first_name ?? ""),
+        lastName: String(c.last_name ?? ""),
+      }),
+  );
+
+  const client = mtprotoService.getClient();
+
+  const result = await mtprotoService.withFloodWaitHandling(async () => {
+    return client.invoke(
+      new Api.contacts.ImportContacts({ contacts: inputContacts }),
+    );
+  });
+
+  const imported = narrow<ImportContactsResult>(result)?.imported?.length ?? 0;
+
+  return {
+    data: { imported, total: contacts.length },
+    fromCache: false,
+  };
+}
diff --git a/src/lib/mcp/telegram/api/index.ts b/src/lib/mcp/telegram/api/index.ts
new file mode 100644
index 000000000..471ac6610
--- /dev/null
+++ b/src/lib/mcp/telegram/api/index.ts
@@ -0,0 +1,104 @@
+/**
+ * Barrel export for the Telegram API layer.
+ *
+ * Each module exposes a single async function returning ApiResult<T>.
+ */
+
+// Foundation
+export type { ApiResult } from "./types";
+export * from "./helpers";
+export * from "./apiResultTypes";
+export * from "./apiCastHelpers";
+
+// Cache-first with API fallback
+export { getChats } from "./getChats";
+export { getMessages } from "./getMessages";
+export { getCurrentUser } from "./getCurrentUser";
+
+// Hybrid (API-first with cache fallback)
+export { getChat } from "./getChat";
+export { resolveUsername } from "./resolveUsername";
+export { searchPublicChats } from "./searchPublicChats";
+export { searchMessages } from "./searchMessages";
+export { getPinnedMessages } from "./getPinnedMessages";
+
+// Cache-only
+export { getContactChats } from "./getContactChats";
+export { getDirectChatByContact } from "./getDirectChatByContact";
+export { getLastInteraction } from "./getLastInteraction";
+export { listInlineButtons } from "./listInlineButtons";
+export { searchChats } from "./searchChats";
+export { getMediaInfo } from "./getMediaInfo";
+
+// Write operations — Chat management
+export { sendMessage } from "./sendMessage";
+export { archiveChat } from "./archiveChat";
+export { unarchiveChat } from "./unarchiveChat";
+export { createChannel } from "./createChannel";
+export { createGroup } from "./createGroup";
+export { editChatTitle } from "./editChatTitle";
+export { leaveChat } from "./leaveChat";
+export { muteChat } from "./muteChat";
+export { unmuteChat } from "./unmuteChat";
+export { deleteChatPhoto } from "./deleteChatPhoto";
+export { editChatPhoto } from "./editChatPhoto";
+export { exportChatInvite } from "./exportChatInvite";
+export { importChatInvite } from "./importChatInvite";
+export { joinChatByLink } from "./joinChatByLink";
+export { subscribePublicChannel } from "./subscribePublicChannel";
+export { getInviteLink } from "./getInviteLink";
+
+// Write operations — Message ops
+export { editMessage } from "./editMessage";
+export { deleteMessage } from "./deleteMessage";
+export { forwardMessage } from "./forwardMessage";
+export { pinMessage } from "./pinMessage";
+export { unpinMessage } from "./unpinMessage";
+export { sendReaction } from "./sendReaction";
+export { removeReaction } from "./removeReaction";
+export { getMessageReactions } from "./getMessageReactions";
+export { pressInlineButton } from "./pressInlineButton";
+export { saveDraft } from "./saveDraft";
+export { getDrafts } from "./getDrafts";
+export { clearDraft } from "./clearDraft";
+export { createPoll } from "./createPoll";
+export { markAsRead } from "./markAsRead";
+
+// Write operations — User/admin
+export { getParticipants } from "./getParticipants";
+export { getAdmins } from "./getAdmins";
+export { getBannedUsers } from "./getBannedUsers";
+export { promoteAdmin } from "./promoteAdmin";
+export { demoteAdmin } from "./demoteAdmin";
+export { banUser } from "./banUser";
+export { unbanUser } from "./unbanUser";
+export { inviteToGroup } from "./inviteToGroup";
+
+// Write operations — Contacts
+export { listContacts } from "./listContacts";
+export { searchContacts } from "./searchContacts";
+export { addContact } from "./addContact";
+export { deleteContact } from "./deleteContact";
+export { blockUser } from "./blockUser";
+export { unblockUser } from "./unblockUser";
+export { getBlockedUsers } from "./getBlockedUsers";
+export { getContactIds } from "./getContactIds";
+export { importContacts } from "./importContacts";
+export { exportContacts } from "./exportContacts";
+
+// Write operations — Profile/settings
+export { updateProfile } from "./updateProfile";
+export { getUserPhotos } from "./getUserPhotos";
+export { getUserStatus } from "./getUserStatus";
+export { getPrivacySettings } from "./getPrivacySettings";
+export { setPrivacySettings } from "./setPrivacySettings";
+export { setProfilePhoto } from "./setProfilePhoto";
+export { deleteProfilePhoto } from "./deleteProfilePhoto";
+export { setBotCommands } from "./setBotCommands";
+export { getBotInfo } from "./getBotInfo";
+
+// Read operations — Search/discovery
+export { getRecentActions } from "./getRecentActions";
+export { getStickerSets } from "./getStickerSets";
+export { getGifSearch } from "./getGifSearch";
+export { listTopics } from "./listTopics";
diff --git a/src/lib/mcp/telegram/api/inviteToGroup.ts b/src/lib/mcp/telegram/api/inviteToGroup.ts
new file mode 100644
index 000000000..9bf97c665
--- /dev/null
+++ b/src/lib/mcp/telegram/api/inviteToGroup.ts
@@ -0,0 +1,56 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import bigInt from "big-integer";
+import { toInputChannel, toInputUser } from "./apiCastHelpers";
+import { getChatById } from "./helpers";
+
+export async function inviteToGroup(
+  chatId: string | number,
+  userIds: string[],
+): Promise<ApiResult<void>> {
+  if (userIds.length === 0) {
+    throw new Error("user_ids must not be empty");
+  }
+
+  const chat = getChatById(chatId);
+  if (!chat) {
+    throw new Error(`Chat not found: ${chatId}`);
+  }
+
+  const client = mtprotoService.getClient();
+  const entity = chat.username ? chat.username : chat.id;
+
+  const users: Api.TypeInputUser[] = [];
+  for (const uid of userIds) {
+    const inputUser = await client.getInputEntity(String(uid));
+    users.push(toInputUser(inputUser));
+  }
+
+  const inputPeer = await client.getInputEntity(entity);
+
+  if (chat.type === "channel" || chat.type === "supergroup") {
+    await mtprotoService.withFloodWaitHandling(async () => {
+      await client.invoke(
+        new Api.channels.InviteToChannel({
+          channel: toInputChannel(inputPeer),
+          users,
+        }),
+      );
+    });
+  } else {
+    for (const user of users) {
+      await mtprotoService.withFloodWaitHandling(async () => {
+        await client.invoke(
+          new Api.messages.AddChatUser({
+            chatId: bigInt(chat.id),
+            userId: user,
+            fwdLimit: 100,
+          }),
+        );
+      });
+    }
+  }
+
+  return { data: undefined, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/joinChatByLink.ts b/src/lib/mcp/telegram/api/joinChatByLink.ts
new file mode 100644
index 000000000..5c6757076
--- /dev/null
+++ b/src/lib/mcp/telegram/api/joinChatByLink.ts
@@ -0,0 +1,27 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import type { ResultWithChats } from "./apiResultTypes";
+import { narrow } from "./apiCastHelpers";
+
+export async function joinChatByLink(
+  link: string,
+): Promise<ApiResult<{ chatTitle: string }>> {
+  // Extract hash from link
+  let hash = link;
+  const plusMatch = link.match(/t\.me\/\+(.+)/);
+  const joinMatch = link.match(/t\.me\/joinchat\/(.+)/);
+  if (plusMatch) hash = plusMatch[1];
+  else if (joinMatch) hash = joinMatch[1];
+
+  const client = mtprotoService.getClient();
+
+  const result = await mtprotoService.withFloodWaitHandling(async () => {
+    return client.invoke(new Api.messages.ImportChatInvite({ hash }));
+  });
+
+  const chatTitle =
+    narrow<ResultWithChats>(result)?.chats?.[0]?.title ?? "unknown";
+
+  return { data: { chatTitle }, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/leaveChat.ts b/src/lib/mcp/telegram/api/leaveChat.ts
new file mode 100644
index 000000000..7898c8d4a
--- /dev/null
+++ b/src/lib/mcp/telegram/api/leaveChat.ts
@@ -0,0 +1,38 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import { getChatById } from "./helpers";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import bigInt from "big-integer";
+import { toInputChannel } from "./apiCastHelpers";
+
+export async function leaveChat(
+  chatId: string | number,
+): Promise<ApiResult<void>> {
+  const chat = getChatById(chatId);
+  if (!chat) throw new Error(`Chat not found: ${chatId}`);
+
+  const client = mtprotoService.getClient();
+  const entity = chat.username ? chat.username : chat.id;
+
+  if (chat.type === "channel" || chat.type === "supergroup") {
+    await mtprotoService.withFloodWaitHandling(async () => {
+      const inputChannel = await client.getInputEntity(entity);
+      await client.invoke(
+        new Api.channels.LeaveChannel({
+          channel: toInputChannel(inputChannel),
+        }),
+      );
+    });
+  } else {
+    await mtprotoService.withFloodWaitHandling(async () => {
+      await client.invoke(
+        new Api.messages.DeleteChatUser({
+          chatId: bigInt(chat.id),
+          userId: new Api.InputUserSelf(),
+        }),
+      );
+    });
+  }
+
+  return { data: undefined as unknown as void, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/listContacts.ts b/src/lib/mcp/telegram/api/listContacts.ts
new file mode 100644
index 000000000..0bb2a7cef
--- /dev/null
+++ b/src/lib/mcp/telegram/api/listContacts.ts
@@ -0,0 +1,33 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import bigInt from "big-integer";
+import type { ApiUser } from "./apiResultTypes";
+
+export interface Contact {
+  id: string;
+  name: string;
+  username?: string;
+  phone?: string;
+}
+
+export async function listContacts(): Promise<ApiResult<Contact[]>> {
+  const client = mtprotoService.getClient();
+
+  const result = await mtprotoService.withFloodWaitHandling(async () => {
+    return client.invoke(new Api.contacts.GetContacts({ hash: bigInt(0) }));
+  });
+
+  if (!result || !("users" in result) || !Array.isArray(result.users)) {
+    return { data: [], fromCache: false };
+  }
+
+  const contacts: Contact[] = result.users.map((u: ApiUser) => ({
+    id: String(u.id),
+    name: [u.firstName, u.lastName].filter(Boolean).join(" ") || "Unknown",
+    username: u.username,
+    phone: u.phone,
+  }));
+
+  return { data: contacts, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/listInlineButtons.ts b/src/lib/mcp/telegram/api/listInlineButtons.ts
new file mode 100644
index 000000000..032fb442c
--- /dev/null
+++ b/src/lib/mcp/telegram/api/listInlineButtons.ts
@@ -0,0 +1,45 @@
+/**
+ * API: List inline buttons — cache-only.
+ */
+
+import type { ApiResult } from "./types";
+import { getChatById, getCachedMessages } from "./helpers";
+import { narrow } from "./apiCastHelpers";
+import type {
+  MessageWithReplyMarkup,
+  ReplyMarkupRow,
+} from "./apiResultTypes";
+
+export interface InlineButton {
+  row: number;
+  button: number;
+  text: string;
+}
+
+export async function listInlineButtons(
+  chatId: string | number,
+  messageId: number,
+): Promise<ApiResult<InlineButton[]>> {
+  const chat = getChatById(chatId);
+  if (!chat) return { data: [], fromCache: true };
+
+  const messages = getCachedMessages(chatId, 200, 0);
+  if (!messages) return { data: [], fromCache: true };
+
+  const found = messages.find((m) => String(m.id) === String(messageId));
+  const msg = found ? narrow<MessageWithReplyMarkup>(found) : undefined;
+  if (!msg || !msg.replyMarkup || !msg.replyMarkup.rows) {
+    return { data: [], fromCache: true };
+  }
+
+  const buttons: InlineButton[] = [];
+  msg.replyMarkup.rows.forEach((row: ReplyMarkupRow, ri: number) => {
+    if (row.buttons) {
+      row.buttons.forEach((btn, bi: number) => {
+        buttons.push({ row: ri, button: bi, text: btn.text ?? "?" });
+      });
+    }
+  });
+
+  return { data: buttons, fromCache: true };
+}
diff --git a/src/lib/mcp/telegram/api/listTopics.ts b/src/lib/mcp/telegram/api/listTopics.ts
new file mode 100644
index 000000000..762aa5178
--- /dev/null
+++ b/src/lib/mcp/telegram/api/listTopics.ts
@@ -0,0 +1,60 @@
+/**
+ * List Topics API - List forum topics in a chat
+ *
+ * Fetches forum topics from channels/supergroups only.
+ */
+
+import { mtprotoService } from "../../../../services/mtprotoService";
+import { getChatById } from "./helpers";
+import type { ApiResult } from "./types";
+import type { ForumTopicsResult } from "./apiResultTypes";
+import { toInputChannel, narrow } from "./apiCastHelpers";
+import { Api } from "telegram";
+
+export interface TopicResult {
+  id: number;
+  title: string;
+}
+
+export async function listTopics(
+  chatId: string | number,
+): Promise<ApiResult<TopicResult[]>> {
+  const chat = getChatById(chatId);
+  if (!chat) {
+    throw new Error("Chat not found: " + chatId);
+  }
+
+  if (chat.type !== "channel" && chat.type !== "supergroup") {
+    throw new Error(
+      "Forum topics are only available for channels/supergroups.",
+    );
+  }
+
+  const client = mtprotoService.getClient();
+  const entity = chat.username ? chat.username : chat.id;
+
+  const result = await mtprotoService.withFloodWaitHandling(async () => {
+    const inputChannel = await client.getInputEntity(entity);
+    return client.invoke(
+      new Api.channels.GetForumTopics({
+        channel: toInputChannel(inputChannel),
+        offsetDate: 0,
+        offsetId: 0,
+        offsetTopic: 0,
+        limit: 100,
+      }),
+    );
+  });
+
+  const topics = narrow<ForumTopicsResult>(result)?.topics;
+  if (!topics || !Array.isArray(topics) || topics.length === 0) {
+    return { data: [], fromCache: false };
+  }
+
+  const topicResults: TopicResult[] = topics.map((t) => ({
+    id: t.id,
+    title: t.title ?? "Untitled",
+  }));
+
+  return { data: topicResults, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/markAsRead.ts b/src/lib/mcp/telegram/api/markAsRead.ts
new file mode 100644
index 000000000..64929557f
--- /dev/null
+++ b/src/lib/mcp/telegram/api/markAsRead.ts
@@ -0,0 +1,27 @@
+/**
+ * API: Mark as read
+ */
+
+import { mtprotoService } from "../../../../services/mtprotoService";
+import { getChatById } from "./helpers";
+import type { ApiResult } from "./types";
+
+export async function markAsRead(
+  chatId: string | number,
+): Promise<ApiResult<void>> {
+  const chat = getChatById(chatId);
+  if (!chat) {
+    throw new Error(`Chat not found: ${chatId}`);
+  }
+
+  const entity = chat.username
+    ? `@${chat.username.replace("@", "")}`
+    : chat.id;
+  const client = mtprotoService.getClient();
+
+  await mtprotoService.withFloodWaitHandling(async () => {
+    await client.markAsRead(entity);
+  });
+
+  return { data: undefined as unknown as void, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/muteChat.ts b/src/lib/mcp/telegram/api/muteChat.ts
new file mode 100644
index 000000000..6298fd4ec
--- /dev/null
+++ b/src/lib/mcp/telegram/api/muteChat.ts
@@ -0,0 +1,34 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import { getChatById } from "./helpers";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+
+export async function muteChat(
+  chatId: string | number,
+  duration?: number,
+): Promise<ApiResult<void>> {
+  const chat = getChatById(chatId);
+  if (!chat) throw new Error(`Chat not found: ${chatId}`);
+
+  const client = mtprotoService.getClient();
+  const entity = chat.username ? chat.username : chat.id;
+
+  const muteUntil =
+    duration === 0 || duration === undefined
+      ? 2147483647
+      : Math.floor(Date.now() / 1000) + duration;
+
+  await mtprotoService.withFloodWaitHandling(async () => {
+    const inputPeer = await client.getInputEntity(entity);
+    await client.invoke(
+      new Api.account.UpdateNotifySettings({
+        peer: new Api.InputNotifyPeer({ peer: inputPeer }),
+        settings: new Api.InputPeerNotifySettings({
+          muteUntil,
+        }),
+      }),
+    );
+  });
+
+  return { data: undefined as unknown as void, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/pinMessage.ts b/src/lib/mcp/telegram/api/pinMessage.ts
new file mode 100644
index 000000000..f56e1882f
--- /dev/null
+++ b/src/lib/mcp/telegram/api/pinMessage.ts
@@ -0,0 +1,28 @@
+/**
+ * API: Pin message
+ */
+
+import { mtprotoService } from "../../../../services/mtprotoService";
+import { getChatById } from "./helpers";
+import type { ApiResult } from "./types";
+
+export async function pinMessage(
+  chatId: string | number,
+  messageId: number,
+): Promise<ApiResult<void>> {
+  const chat = getChatById(chatId);
+  if (!chat) {
+    throw new Error(`Chat not found: ${chatId}`);
+  }
+
+  const entity = chat.username
+    ? `@${chat.username.replace("@", "")}`
+    : chat.id;
+  const client = mtprotoService.getClient();
+
+  await mtprotoService.withFloodWaitHandling(async () => {
+    await client.pinMessage(entity, messageId, { notify: false });
+  });
+
+  return { data: undefined as unknown as void, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/pressInlineButton.ts b/src/lib/mcp/telegram/api/pressInlineButton.ts
new file mode 100644
index 000000000..99f540862
--- /dev/null
+++ b/src/lib/mcp/telegram/api/pressInlineButton.ts
@@ -0,0 +1,43 @@
+/**
+ * API: Press inline button
+ */
+
+import { mtprotoService } from "../../../../services/mtprotoService";
+import { getChatById } from "./helpers";
+import type { ApiResult } from "./types";
+import type { BotCallbackAnswer } from "./apiResultTypes";
+import { Api } from "telegram";
+import { narrow } from "./apiCastHelpers";
+
+export async function pressInlineButton(
+  chatId: string | number,
+  messageId: number,
+  buttonData: string,
+): Promise<ApiResult<string>> {
+  const chat = getChatById(chatId);
+  if (!chat) {
+    throw new Error(`Chat not found: ${chatId}`);
+  }
+
+  const client = mtprotoService.getClient();
+  const entity = chat.username
+    ? `@${chat.username.replace("@", "")}`
+    : chat.id;
+
+  const result = await mtprotoService.withFloodWaitHandling(async () => {
+    const inputPeer = await client.getInputEntity(entity);
+    return client.invoke(
+      new Api.messages.GetBotCallbackAnswer({
+        peer: inputPeer,
+        msgId: messageId,
+        data: Buffer.from(buttonData, "base64"),
+      }),
+    );
+  });
+
+  const answer =
+    narrow<BotCallbackAnswer>(result)?.message ??
+    "Button pressed (no response message).";
+
+  return { data: answer, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/promoteAdmin.ts b/src/lib/mcp/telegram/api/promoteAdmin.ts
new file mode 100644
index 000000000..572597c2b
--- /dev/null
+++ b/src/lib/mcp/telegram/api/promoteAdmin.ts
@@ -0,0 +1,46 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import { toInputChannel, toInputUser } from "./apiCastHelpers";
+import { getChatById } from "./helpers";
+
+export async function promoteAdmin(
+  chatId: string | number,
+  userId: string | number,
+): Promise<ApiResult<void>> {
+  const chat = getChatById(chatId);
+  if (!chat) {
+    throw new Error(`Chat not found: ${chatId}`);
+  }
+
+  if (chat.type !== "channel" && chat.type !== "supergroup") {
+    throw new Error(
+      "Admin promotion is only available for channels/supergroups.",
+    );
+  }
+
+  const client = mtprotoService.getClient();
+  const entity = chat.username ? chat.username : chat.id;
+
+  await mtprotoService.withFloodWaitHandling(async () => {
+    const inputChannel = await client.getInputEntity(entity);
+    const inputUser = await client.getInputEntity(userId);
+    await client.invoke(
+      new Api.channels.EditAdmin({
+        channel: toInputChannel(inputChannel),
+        userId: toInputUser(inputUser),
+        adminRights: new Api.ChatAdminRights({
+          changeInfo: true,
+          deleteMessages: true,
+          banUsers: true,
+          inviteUsers: true,
+          pinMessages: true,
+          manageCall: true,
+        }),
+        rank: "Admin",
+      }),
+    );
+  });
+
+  return { data: undefined, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/removeReaction.ts b/src/lib/mcp/telegram/api/removeReaction.ts
new file mode 100644
index 000000000..2ef62d18e
--- /dev/null
+++ b/src/lib/mcp/telegram/api/removeReaction.ts
@@ -0,0 +1,36 @@
+/**
+ * API: Remove reaction
+ */
+
+import { mtprotoService } from "../../../../services/mtprotoService";
+import { getChatById } from "./helpers";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+
+export async function removeReaction(
+  chatId: string | number,
+  messageId: number,
+): Promise<ApiResult<void>> {
+  const chat = getChatById(chatId);
+  if (!chat) {
+    throw new Error(`Chat not found: ${chatId}`);
+  }
+
+  const client = mtprotoService.getClient();
+  const entity = chat.username
+    ? `@${chat.username.replace("@", "")}`
+    : chat.id;
+
+  await mtprotoService.withFloodWaitHandling(async () => {
+    const inputPeer = await client.getInputEntity(entity);
+    await client.invoke(
+      new Api.messages.SendReaction({
+        peer: inputPeer,
+        msgId: messageId,
+        reaction: [],
+      }),
+    );
+  });
+
+  return { data: undefined as unknown as void, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/resolveUsername.ts b/src/lib/mcp/telegram/api/resolveUsername.ts
new file mode 100644
index 000000000..c6d19e63b
--- /dev/null
+++ b/src/lib/mcp/telegram/api/resolveUsername.ts
@@ -0,0 +1,95 @@
+/**
+ * API: Resolve username — API-first with cache fallback (hybrid).
+ */
+
+import { mtprotoService } from "../../../../services/mtprotoService";
+import { Api } from "telegram";
+import { getChatById, formatEntity } from "./helpers";
+import type { ApiResult } from "./types";
+
+export interface ResolvedEntity {
+  id: string;
+  name: string;
+  type: string;
+  username: string;
+}
+
+export async function resolveUsername(
+  username: string,
+): Promise<ApiResult<ResolvedEntity | undefined>> {
+  const clean = username.startsWith("@") ? username.slice(1) : username;
+
+  // 1. Try server-side resolution via Telegram API
+  try {
+    const client = mtprotoService.getClient();
+
+    const result = await mtprotoService.withFloodWaitHandling(async () => {
+      return client.invoke(
+        new Api.contacts.ResolveUsername({ username: clean }),
+      );
+    });
+
+    if (result && "peer" in result) {
+      const peer = result.peer;
+      const peerType =
+        peer.className === "PeerUser"
+          ? "user"
+          : peer.className === "PeerChannel"
+            ? "channel"
+            : peer.className === "PeerChat"
+              ? "chat"
+              : "unknown";
+
+      const peerId =
+        "userId" in peer
+          ? String(peer.userId)
+          : "channelId" in peer
+            ? String(peer.channelId)
+            : "chatId" in peer
+              ? String(peer.chatId)
+              : "unknown";
+
+      let name = clean;
+      if ("users" in result && Array.isArray(result.users)) {
+        const user = result.users[0] as {
+          firstName?: string;
+          lastName?: string;
+        };
+        if (user) {
+          name =
+            [user.firstName, user.lastName].filter(Boolean).join(" ") || clean;
+        }
+      }
+      if ("chats" in result && Array.isArray(result.chats)) {
+        const chat = result.chats[0] as { title?: string };
+        if (chat?.title) {
+          name = chat.title;
+        }
+      }
+
+      return {
+        data: { id: peerId, name, type: peerType, username: clean },
+        fromCache: false,
+      };
+    }
+  } catch {
+    // API call failed — fall back to cached lookup below
+  }
+
+  // 2. Fallback: look up from cached state
+  const lookupKey = `@${clean}`;
+  const chat = getChatById(lookupKey);
+  if (!chat) {
+    return { data: undefined, fromCache: false };
+  }
+  const entity = formatEntity(chat);
+  return {
+    data: {
+      id: entity.id,
+      name: entity.name,
+      type: entity.type,
+      username: entity.username ?? clean,
+    },
+    fromCache: true,
+  };
+}
diff --git a/src/lib/mcp/telegram/api/saveDraft.ts b/src/lib/mcp/telegram/api/saveDraft.ts
new file mode 100644
index 000000000..182e8b4d3
--- /dev/null
+++ b/src/lib/mcp/telegram/api/saveDraft.ts
@@ -0,0 +1,35 @@
+/**
+ * API: Save draft
+ */
+
+import { mtprotoService } from "../../../../services/mtprotoService";
+import { getChatById } from "./helpers";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+
+export async function saveDraft(
+  chatId: string | number,
+  text: string,
+): Promise<ApiResult<void>> {
+  const chat = getChatById(chatId);
+  if (!chat) {
+    throw new Error(`Chat not found: ${chatId}`);
+  }
+
+  const client = mtprotoService.getClient();
+  const entity = chat.username
+    ? `@${chat.username.replace("@", "")}`
+    : chat.id;
+
+  await mtprotoService.withFloodWaitHandling(async () => {
+    const inputPeer = await client.getInputEntity(entity);
+    await client.invoke(
+      new Api.messages.SaveDraft({
+        peer: inputPeer,
+        message: text,
+      }),
+    );
+  });
+
+  return { data: undefined as unknown as void, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/searchChats.ts b/src/lib/mcp/telegram/api/searchChats.ts
new file mode 100644
index 000000000..aa397815b
--- /dev/null
+++ b/src/lib/mcp/telegram/api/searchChats.ts
@@ -0,0 +1,14 @@
+/**
+ * API: Search chats — cache-only.
+ */
+
+import type { TelegramChat } from "../../../../store/telegram/types";
+import { searchChatsInCache } from "./helpers";
+import type { ApiResult } from "./types";
+
+export async function searchChats(
+  query: string,
+): Promise<ApiResult<TelegramChat[]>> {
+  const data = searchChatsInCache(query);
+  return { data, fromCache: true };
+}
diff --git a/src/lib/mcp/telegram/api/searchContacts.ts b/src/lib/mcp/telegram/api/searchContacts.ts
new file mode 100644
index 000000000..d90a743bb
--- /dev/null
+++ b/src/lib/mcp/telegram/api/searchContacts.ts
@@ -0,0 +1,42 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import type { ApiUser } from "./apiResultTypes";
+
+export interface ContactSearchResult {
+  id: string;
+  name: string;
+  username?: string;
+}
+
+export async function searchContacts(
+  query: string,
+  limit: number = 20,
+): Promise<ApiResult<ContactSearchResult[]>> {
+  if (!query) {
+    throw new Error("query is required");
+  }
+
+  const client = mtprotoService.getClient();
+
+  const result = await mtprotoService.withFloodWaitHandling(async () => {
+    return client.invoke(new Api.contacts.Search({ q: query, limit }));
+  });
+
+  if (
+    !result ||
+    !("users" in result) ||
+    !Array.isArray(result.users) ||
+    result.users.length === 0
+  ) {
+    return { data: [], fromCache: false };
+  }
+
+  const contacts: ContactSearchResult[] = result.users.map((u: ApiUser) => ({
+    id: String(u.id),
+    name: [u.firstName, u.lastName].filter(Boolean).join(" ") || "Unknown",
+    username: u.username,
+  }));
+
+  return { data: contacts, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/searchMessages.ts b/src/lib/mcp/telegram/api/searchMessages.ts
new file mode 100644
index 000000000..9e23ba3f2
--- /dev/null
+++ b/src/lib/mcp/telegram/api/searchMessages.ts
@@ -0,0 +1,93 @@
+/**
+ * API: Search messages (API-first with cache fallback)
+ */
+
+import { mtprotoService } from "../../../../services/mtprotoService";
+import { getChatById, formatMessage, getCachedMessages } from "./helpers";
+import type { ApiResult } from "./types";
+import type { ApiMessage } from "./apiResultTypes";
+import { Api } from "telegram";
+import bigInt from "big-integer";
+import { narrow } from "./apiCastHelpers";
+
+export interface SearchedMessage {
+  id: number | string;
+  date: string;
+  text: string;
+  from?: string;
+}
+
+export async function searchMessages(
+  chatId: string | number,
+  query: string,
+  limit: number,
+): Promise<ApiResult<SearchedMessage[]>> {
+  const chat = getChatById(chatId);
+  if (!chat) {
+    throw new Error(`Chat not found: ${chatId}`);
+  }
+
+  // Try API first
+  try {
+    const client = mtprotoService.getClient();
+    const entity = chat.username
+      ? `@${chat.username.replace("@", "")}`
+      : chat.id;
+    const inputPeer = await client.getInputEntity(entity);
+
+    const result = await mtprotoService.withFloodWaitHandling(async () => {
+      return client.invoke(
+        new Api.messages.Search({
+          peer: inputPeer,
+          q: query,
+          filter: new Api.InputMessagesFilterEmpty(),
+          minDate: 0,
+          maxDate: 0,
+          offsetId: 0,
+          addOffset: 0,
+          limit,
+          maxId: 0,
+          minId: 0,
+          hash: bigInt(0),
+        }),
+      );
+    });
+
+    if ("messages" in result && Array.isArray(result.messages)) {
+      const messages = narrow<ApiMessage[]>(result.messages);
+      const searchedMessages = messages.map((msg) => ({
+        id: msg.id ?? "?",
+        date: msg.date
+          ? new Date(msg.date * 1000).toISOString()
+          : "unknown",
+        text: msg.message ?? "[Media/No text]",
+      }));
+      return { data: searchedMessages, fromCache: false };
+    }
+  } catch {
+    // API failed, fall back to cache below
+  }
+
+  // Fallback: search cached messages
+  const cachedMessages = getCachedMessages(chatId, limit * 3, 0);
+
+  if (cachedMessages) {
+    const q = query.toLowerCase();
+    const filtered = cachedMessages
+      .filter((msg) => msg.message.toLowerCase().includes(q))
+      .slice(0, limit);
+
+    const searchedMessages = filtered.map((msg) => {
+      const f = formatMessage(msg);
+      return {
+        id: f.id,
+        date: f.date,
+        text: f.text || "[Media]",
+        from: msg.fromName ?? msg.fromId ?? "Unknown",
+      };
+    });
+    return { data: searchedMessages, fromCache: true };
+  }
+
+  return { data: [], fromCache: true };
+}
diff --git a/src/lib/mcp/telegram/api/searchPublicChats.ts b/src/lib/mcp/telegram/api/searchPublicChats.ts
new file mode 100644
index 000000000..3194f9b6c
--- /dev/null
+++ b/src/lib/mcp/telegram/api/searchPublicChats.ts
@@ -0,0 +1,96 @@
+/**
+ * Search Public Chats API - Search for public chats, channels, or bots
+ *
+ * Uses Telegram's contacts.Search API for server-side discovery.
+ * Falls back to filtering cached chats if the API call fails.
+ */
+
+import { mtprotoService } from "../../../../services/mtprotoService";
+import { searchChatsInCache } from "./helpers";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+
+export interface PublicChatResult {
+  id: string;
+  name: string;
+  type: string;
+  username?: string;
+}
+
+export async function searchPublicChats(
+  query: string,
+): Promise<ApiResult<PublicChatResult[]>> {
+  // Try server-side search via Telegram API
+  try {
+    const client = mtprotoService.getClient();
+
+    const result = await mtprotoService.withFloodWaitHandling(async () => {
+      return client.invoke(new Api.contacts.Search({ q: query, limit: 20 }));
+    });
+
+    const entries: PublicChatResult[] = [];
+
+    // Process returned chats
+    if ("chats" in result && Array.isArray(result.chats)) {
+      for (const chat of result.chats) {
+        const c = chat as {
+          id: { toString(): string };
+          title?: string;
+          username?: string;
+          megagroup?: boolean;
+          broadcast?: boolean;
+        };
+        const type = c.broadcast
+          ? "channel"
+          : c.megagroup
+            ? "group"
+            : "chat";
+        entries.push({
+          id: String(c.id),
+          name: c.title ?? "Unknown",
+          type,
+          username: c.username,
+        });
+      }
+    }
+
+    // Process returned users
+    if ("users" in result && Array.isArray(result.users)) {
+      for (const user of result.users) {
+        const u = user as {
+          id: { toString(): string };
+          firstName?: string;
+          lastName?: string;
+          username?: string;
+          bot?: boolean;
+        };
+        const name =
+          [u.firstName, u.lastName].filter(Boolean).join(" ") || "Unknown";
+        entries.push({
+          id: String(u.id),
+          name,
+          type: u.bot ? "bot" : "user",
+          username: u.username,
+        });
+      }
+    }
+
+    if (entries.length > 0) {
+      return { data: entries, fromCache: false };
+    }
+  } catch {
+    // API call failed — fall back to cached search
+  }
+
+  // Fallback: search cached chats locally
+  const chats = searchChatsInCache(query);
+  return {
+    data: chats.map((c) => ({
+      id: c.id,
+      name: c.title ?? "Unknown",
+      type: c.type ?? "chat",
+      username: c.username,
+    })),
+    fromCache: true,
+  };
+}
diff --git a/src/lib/mcp/telegram/api/sendMessage.ts b/src/lib/mcp/telegram/api/sendMessage.ts
new file mode 100644
index 000000000..39f108931
--- /dev/null
+++ b/src/lib/mcp/telegram/api/sendMessage.ts
@@ -0,0 +1,34 @@
+/**
+ * API: Send message — always API (write operation).
+ */
+
+import { mtprotoService } from "../../../../services/mtprotoService";
+import { getChatById } from "./helpers";
+import type { ApiResult } from "./types";
+
+export async function sendMessage(
+  chatId: string | number,
+  message: string,
+  replyToMessageId?: number,
+): Promise<ApiResult<{ id: string } | undefined>> {
+  const chat = getChatById(chatId);
+  if (!chat) return { data: undefined, fromCache: false };
+
+  const entity = chat.username
+    ? `@${chat.username.replace("@", "")}`
+    : chat.id;
+
+  if (replyToMessageId !== undefined) {
+    const client = mtprotoService.getClient();
+    await mtprotoService.withFloodWaitHandling(async () => {
+      await client.sendMessage(entity, {
+        message,
+        replyTo: replyToMessageId,
+      });
+    });
+  } else {
+    await mtprotoService.sendMessage(entity, message);
+  }
+
+  return { data: { id: String(Date.now()) }, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/sendReaction.ts b/src/lib/mcp/telegram/api/sendReaction.ts
new file mode 100644
index 000000000..0af0ac0a5
--- /dev/null
+++ b/src/lib/mcp/telegram/api/sendReaction.ts
@@ -0,0 +1,37 @@
+/**
+ * API: Send reaction
+ */
+
+import { mtprotoService } from "../../../../services/mtprotoService";
+import { getChatById } from "./helpers";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+
+export async function sendReaction(
+  chatId: string | number,
+  messageId: number,
+  emoji: string,
+): Promise<ApiResult<void>> {
+  const chat = getChatById(chatId);
+  if (!chat) {
+    throw new Error(`Chat not found: ${chatId}`);
+  }
+
+  const client = mtprotoService.getClient();
+  const entity = chat.username
+    ? `@${chat.username.replace("@", "")}`
+    : chat.id;
+
+  await mtprotoService.withFloodWaitHandling(async () => {
+    const inputPeer = await client.getInputEntity(entity);
+    await client.invoke(
+      new Api.messages.SendReaction({
+        peer: inputPeer,
+        msgId: messageId,
+        reaction: [new Api.ReactionEmoji({ emoticon: emoji })],
+      }),
+    );
+  });
+
+  return { data: undefined as unknown as void, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/setBotCommands.ts b/src/lib/mcp/telegram/api/setBotCommands.ts
new file mode 100644
index 000000000..02a1caa41
--- /dev/null
+++ b/src/lib/mcp/telegram/api/setBotCommands.ts
@@ -0,0 +1,34 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import type { BotCommandInput } from "./apiResultTypes";
+
+export async function setBotCommands(
+  commands: BotCommandInput[],
+): Promise<ApiResult<number>> {
+  if (!Array.isArray(commands) || commands.length === 0) {
+    throw new Error("commands array is required and must not be empty");
+  }
+
+  const client = mtprotoService.getClient();
+
+  const botCommands = commands.map(
+    (c: BotCommandInput) =>
+      new Api.BotCommand({
+        command: String(c.command ?? ""),
+        description: String(c.description ?? ""),
+      }),
+  );
+
+  await mtprotoService.withFloodWaitHandling(async () => {
+    await client.invoke(
+      new Api.bots.SetBotCommands({
+        scope: new Api.BotCommandScopeDefault(),
+        langCode: "",
+        commands: botCommands,
+      }),
+    );
+  });
+
+  return { data: commands.length, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/setPrivacySettings.ts b/src/lib/mcp/telegram/api/setPrivacySettings.ts
new file mode 100644
index 000000000..3460559eb
--- /dev/null
+++ b/src/lib/mcp/telegram/api/setPrivacySettings.ts
@@ -0,0 +1,68 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+
+export type PrivacyKey =
+  | "phone_number"
+  | "last_seen"
+  | "profile_photo"
+  | "forwards"
+  | "phone_call"
+  | "chat_invite";
+
+export type PrivacyRule = "allow_all" | "allow_contacts" | "disallow_all";
+
+const keyMap: Record<PrivacyKey, Api.TypeInputPrivacyKey> = {
+  phone_number: new Api.InputPrivacyKeyPhoneNumber(),
+  last_seen: new Api.InputPrivacyKeyStatusTimestamp(),
+  profile_photo: new Api.InputPrivacyKeyProfilePhoto(),
+  forwards: new Api.InputPrivacyKeyForwards(),
+  phone_call: new Api.InputPrivacyKeyPhoneCall(),
+  chat_invite: new Api.InputPrivacyKeyChatInvite(),
+};
+
+const ruleMap: Record<PrivacyRule, Api.TypeInputPrivacyRule> = {
+  allow_all: new Api.InputPrivacyValueAllowAll(),
+  allow_contacts: new Api.InputPrivacyValueAllowContacts(),
+  disallow_all: new Api.InputPrivacyValueDisallowAll(),
+};
+
+export async function setPrivacySettings(
+  setting: string,
+  value: string,
+): Promise<ApiResult<void>> {
+  if (!setting) {
+    throw new Error("setting is required");
+  }
+  if (!value) {
+    throw new Error("value is required");
+  }
+
+  if (!(setting in keyMap)) {
+    throw new Error("Unknown privacy key: " + setting);
+  }
+
+  if (!(value in ruleMap)) {
+    throw new Error(
+      "Unknown rule: " +
+        value +
+        ". Valid: allow_all, allow_contacts, disallow_all",
+    );
+  }
+
+  const privacyKey = setting as PrivacyKey;
+  const privacyRule = value as PrivacyRule;
+
+  const client = mtprotoService.getClient();
+
+  await mtprotoService.withFloodWaitHandling(async () => {
+    await client.invoke(
+      new Api.account.SetPrivacy({
+        key: keyMap[privacyKey],
+        rules: [ruleMap[privacyRule]],
+      }),
+    );
+  });
+
+  return { data: undefined, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/setProfilePhoto.ts b/src/lib/mcp/telegram/api/setProfilePhoto.ts
new file mode 100644
index 000000000..4c9303dde
--- /dev/null
+++ b/src/lib/mcp/telegram/api/setProfilePhoto.ts
@@ -0,0 +1,9 @@
+import type { ApiResult } from "./types";
+
+export async function setProfilePhoto(
+  _filePath: string,
+): Promise<ApiResult<void>> {
+  throw new Error(
+    "set_profile_photo requires file upload which is not supported via MCP text interface. Use the Telegram client directly.",
+  );
+}
diff --git a/src/lib/mcp/telegram/api/subscribePublicChannel.ts b/src/lib/mcp/telegram/api/subscribePublicChannel.ts
new file mode 100644
index 000000000..787710496
--- /dev/null
+++ b/src/lib/mcp/telegram/api/subscribePublicChannel.ts
@@ -0,0 +1,21 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import { toInputChannel } from "./apiCastHelpers";
+
+export async function subscribePublicChannel(
+  username: string,
+): Promise<ApiResult<void>> {
+  const client = mtprotoService.getClient();
+
+  await mtprotoService.withFloodWaitHandling(async () => {
+    const inputChannel = await client.getInputEntity(username);
+    await client.invoke(
+      new Api.channels.JoinChannel({
+        channel: toInputChannel(inputChannel),
+      }),
+    );
+  });
+
+  return { data: undefined as unknown as void, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/types.ts b/src/lib/mcp/telegram/api/types.ts
new file mode 100644
index 000000000..17283d906
--- /dev/null
+++ b/src/lib/mcp/telegram/api/types.ts
@@ -0,0 +1,12 @@
+/**
+ * API layer types for Telegram MCP
+ *
+ * Every API function returns ApiResult<T> which carries both the data
+ * and a `fromCache` boolean indicating whether it was served from Redux
+ * cache or fetched from the Telegram API.
+ */
+
+export interface ApiResult<T> {
+  data: T;
+  fromCache: boolean;
+}
diff --git a/src/lib/mcp/telegram/api/unarchiveChat.ts b/src/lib/mcp/telegram/api/unarchiveChat.ts
new file mode 100644
index 000000000..c7f26160c
--- /dev/null
+++ b/src/lib/mcp/telegram/api/unarchiveChat.ts
@@ -0,0 +1,30 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import { getChatById } from "./helpers";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+
+export async function unarchiveChat(
+  chatId: string | number,
+): Promise<ApiResult<void>> {
+  const chat = getChatById(chatId);
+  if (!chat) throw new Error(`Chat not found: ${chatId}`);
+
+  const client = mtprotoService.getClient();
+  const entity = chat.username ? chat.username : chat.id;
+
+  await mtprotoService.withFloodWaitHandling(async () => {
+    const inputPeer = await client.getInputEntity(entity);
+    await client.invoke(
+      new Api.folders.EditPeerFolders({
+        folderPeers: [
+          new Api.InputFolderPeer({
+            peer: inputPeer,
+            folderId: 0, // 0 = Main folder (unarchive)
+          }),
+        ],
+      }),
+    );
+  });
+
+  return { data: undefined as unknown as void, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/unbanUser.ts b/src/lib/mcp/telegram/api/unbanUser.ts
new file mode 100644
index 000000000..4338bc2aa
--- /dev/null
+++ b/src/lib/mcp/telegram/api/unbanUser.ts
@@ -0,0 +1,36 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import { toInputChannel, toInputPeer } from "./apiCastHelpers";
+import { getChatById } from "./helpers";
+
+export async function unbanUser(
+  chatId: string | number,
+  userId: string | number,
+): Promise<ApiResult<void>> {
+  const chat = getChatById(chatId);
+  if (!chat) {
+    throw new Error(`Chat not found: ${chatId}`);
+  }
+
+  if (chat.type !== "channel" && chat.type !== "supergroup") {
+    throw new Error("Unban is only available for channels/supergroups.");
+  }
+
+  const client = mtprotoService.getClient();
+  const entity = chat.username ? chat.username : chat.id;
+
+  await mtprotoService.withFloodWaitHandling(async () => {
+    const inputChannel = await client.getInputEntity(entity);
+    const inputUser = await client.getInputEntity(userId);
+    await client.invoke(
+      new Api.channels.EditBanned({
+        channel: toInputChannel(inputChannel),
+        participant: toInputPeer(inputUser),
+        bannedRights: new Api.ChatBannedRights({ untilDate: 0 }),
+      }),
+    );
+  });
+
+  return { data: undefined, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/unblockUser.ts b/src/lib/mcp/telegram/api/unblockUser.ts
new file mode 100644
index 000000000..ea915ac47
--- /dev/null
+++ b/src/lib/mcp/telegram/api/unblockUser.ts
@@ -0,0 +1,17 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+import { toInputPeer } from "./apiCastHelpers";
+
+export async function unblockUser(userId: string | number): Promise<ApiResult<void>> {
+  const client = mtprotoService.getClient();
+
+  await mtprotoService.withFloodWaitHandling(async () => {
+    const inputUser = await client.getInputEntity(userId);
+    await client.invoke(
+      new Api.contacts.Unblock({ id: toInputPeer(inputUser) }),
+    );
+  });
+
+  return { data: undefined, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/unmuteChat.ts b/src/lib/mcp/telegram/api/unmuteChat.ts
new file mode 100644
index 000000000..d4093745a
--- /dev/null
+++ b/src/lib/mcp/telegram/api/unmuteChat.ts
@@ -0,0 +1,28 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import { getChatById } from "./helpers";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+
+export async function unmuteChat(
+  chatId: string | number,
+): Promise<ApiResult<void>> {
+  const chat = getChatById(chatId);
+  if (!chat) throw new Error(`Chat not found: ${chatId}`);
+
+  const client = mtprotoService.getClient();
+  const entity = chat.username ? chat.username : chat.id;
+
+  await mtprotoService.withFloodWaitHandling(async () => {
+    const inputPeer = await client.getInputEntity(entity);
+    await client.invoke(
+      new Api.account.UpdateNotifySettings({
+        peer: new Api.InputNotifyPeer({ peer: inputPeer }),
+        settings: new Api.InputPeerNotifySettings({
+          muteUntil: 0,
+        }),
+      }),
+    );
+  });
+
+  return { data: undefined as unknown as void, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/unpinMessage.ts b/src/lib/mcp/telegram/api/unpinMessage.ts
new file mode 100644
index 000000000..a26fb4f50
--- /dev/null
+++ b/src/lib/mcp/telegram/api/unpinMessage.ts
@@ -0,0 +1,36 @@
+/**
+ * API: Unpin message
+ */
+
+import { mtprotoService } from "../../../../services/mtprotoService";
+import { getChatById } from "./helpers";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+
+export async function unpinMessage(
+  chatId: string | number,
+  messageId: number,
+): Promise<ApiResult<void>> {
+  const chat = getChatById(chatId);
+  if (!chat) {
+    throw new Error(`Chat not found: ${chatId}`);
+  }
+
+  const entity = chat.username
+    ? `@${chat.username.replace("@", "")}`
+    : chat.id;
+  const client = mtprotoService.getClient();
+
+  await mtprotoService.withFloodWaitHandling(async () => {
+    const inputPeer = await client.getInputEntity(entity);
+    await client.invoke(
+      new Api.messages.UpdatePinnedMessage({
+        peer: inputPeer,
+        id: messageId,
+        unpin: true,
+      }),
+    );
+  });
+
+  return { data: undefined as unknown as void, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/api/updateProfile.ts b/src/lib/mcp/telegram/api/updateProfile.ts
new file mode 100644
index 000000000..3330c0619
--- /dev/null
+++ b/src/lib/mcp/telegram/api/updateProfile.ts
@@ -0,0 +1,42 @@
+import { mtprotoService } from "../../../../services/mtprotoService";
+import type { ApiResult } from "./types";
+import { Api } from "telegram";
+
+export interface ProfileUpdate {
+  firstName?: string;
+  lastName?: string;
+  about?: string;
+}
+
+export async function updateProfile(
+  update: ProfileUpdate,
+): Promise<ApiResult<string[]>> {
+  if (
+    !update.firstName &&
+    !update.lastName &&
+    !update.about
+  ) {
+    throw new Error(
+      "At least one of firstName, lastName, or about is required.",
+    );
+  }
+
+  const client = mtprotoService.getClient();
+
+  await mtprotoService.withFloodWaitHandling(async () => {
+    return client.invoke(
+      new Api.account.UpdateProfile({
+        firstName: update.firstName ?? undefined,
+        lastName: update.lastName ?? undefined,
+        about: update.about ?? undefined,
+      }),
+    );
+  });
+
+  const updated: string[] = [];
+  if (update.firstName) updated.push("first_name: " + update.firstName);
+  if (update.lastName) updated.push("last_name: " + update.lastName);
+  if (update.about) updated.push("about: " + update.about);
+
+  return { data: updated, fromCache: false };
+}
diff --git a/src/lib/mcp/telegram/args.test.ts b/src/lib/mcp/telegram/args.test.ts
new file mode 100644
index 000000000..b64abd98b
--- /dev/null
+++ b/src/lib/mcp/telegram/args.test.ts
@@ -0,0 +1,91 @@
+import { describe, it, expect } from "vitest";
+import { optNumber, optString } from "./args";
+
+describe("optNumber", () => {
+  it("returns the number when args[key] is a valid number", () => {
+    const args = { count: 42 };
+    expect(optNumber(args, "count", 0)).toBe(42);
+  });
+
+  it("returns the number when args[key] is zero", () => {
+    const args = { count: 0 };
+    expect(optNumber(args, "count", 10)).toBe(0);
+  });
+
+  it("returns the number when args[key] is negative", () => {
+    const args = { count: -5 };
+    expect(optNumber(args, "count", 0)).toBe(-5);
+  });
+
+  it("returns fallback when args[key] is NaN", () => {
+    const args = { count: NaN };
+    expect(optNumber(args, "count", 100)).toBe(100);
+  });
+
+  it("returns fallback when args[key] is Infinity", () => {
+    const args = { count: Infinity };
+    expect(optNumber(args, "count", 50)).toBe(50);
+  });
+
+  it("returns fallback when args[key] is -Infinity", () => {
+    const args = { count: -Infinity };
+    expect(optNumber(args, "count", 50)).toBe(50);
+  });
+
+  it("returns fallback when args[key] is a string", () => {
+    const args = { count: "123" };
+    expect(optNumber(args, "count", 0)).toBe(0);
+  });
+
+  it("returns fallback when args[key] is undefined", () => {
+    const args = {};
+    expect(optNumber(args, "count", 25)).toBe(25);
+  });
+
+  it("returns fallback when args[key] is null", () => {
+    const args = { count: null };
+    expect(optNumber(args, "count", 99)).toBe(99);
+  });
+
+  it("returns fallback when args[key] is a boolean", () => {
+    const args = { count: true };
+    expect(optNumber(args, "count", 7)).toBe(7);
+  });
+});
+
+describe("optString", () => {
+  it("returns the string when args[key] is a valid string", () => {
+    const args = { name: "alice" };
+    expect(optString(args, "name")).toBe("alice");
+  });
+
+  it("returns empty string when args[key] is an empty string", () => {
+    const args = { name: "" };
+    expect(optString(args, "name")).toBe("");
+  });
+
+  it("returns undefined when args[key] is a number", () => {
+    const args = { name: 123 };
+    expect(optString(args, "name")).toBeUndefined();
+  });
+
+  it("returns undefined when args[key] is undefined", () => {
+    const args = {};
+    expect(optString(args, "name")).toBeUndefined();
+  });
+
+  it("returns undefined when args[key] is null", () => {
+    const args = { name: null };
+    expect(optString(args, "name")).toBeUndefined();
+  });
+
+  it("returns undefined when args[key] is a boolean", () => {
+    const args = { name: false };
+    expect(optString(args, "name")).toBeUndefined();
+  });
+
+  it("returns undefined when args[key] is an object", () => {
+    const args = { name: { nested: "value" } };
+    expect(optString(args, "name")).toBeUndefined();
+  });
+});
diff --git a/src/lib/mcp/telegram/server.test.ts b/src/lib/mcp/telegram/server.test.ts
new file mode 100644
index 000000000..a228454ab
--- /dev/null
+++ b/src/lib/mcp/telegram/server.test.ts
@@ -0,0 +1,604 @@
+/**
+ * E2E integration tests for TelegramMCPServer
+ *
+ * Tests the full pipeline: transport event → server → tool handler → transport emit
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import type { MCPToolResult } from "../types";
+
+// Use vi.hoisted so mock variables are available when vi.mock factories run
+const {
+  mockTransportEmit,
+  mockTransportOn,
+  mockTransportOff,
+  mockTransportUpdateSocket,
+} = vi.hoisted(() => ({
+  mockTransportEmit: vi.fn(),
+  mockTransportOn: vi.fn(),
+  mockTransportOff: vi.fn(),
+  mockTransportUpdateSocket: vi.fn(),
+}));
+
+// Mock the transport module — must use hoisted variables
+vi.mock("../transport", () => ({
+  SocketIOMCPTransportImpl: vi.fn(),
+}));
+
+// Mock the store
+vi.mock("../../../store", () => ({
+  store: {
+    getState: vi.fn(() => ({
+      user: { user: { _id: "u1" } },
+      telegram: {
+        byUser: {
+          u1: {
+            connectionStatus: "connected",
+            authStatus: "authenticated",
+            isInitialized: true,
+            chats: {},
+            chatsOrder: [],
+            messages: {},
+            messagesOrder: {},
+            currentUser: null,
+            users: {},
+            selectedChatId: null,
+            threads: {},
+            threadsOrder: {},
+            selectedThreadId: null,
+            threadIndex: {},
+            isLoadingChats: false,
+            isLoadingMessages: false,
+            isLoadingThreads: false,
+            hasMoreChats: true,
+            hasMoreMessages: {},
+            hasMoreThreads: {},
+            searchQuery: null,
+            filteredChatIds: null,
+            connectionError: null,
+            authError: null,
+            phoneNumber: null,
+            sessionString: null,
+            isSyncing: false,
+            isSynced: false,
+            commonBoxState: { seq: 0, date: 0, pts: 0, qts: 0 },
+            channelPtsById: {},
+          },
+        },
+      },
+    })),
+  },
+}));
+
+vi.mock("../../../store/telegramSelectors", () => ({
+  selectTelegramUserState: vi.fn((state: any) => {
+    const userId = state?.user?.user?._id ?? "";
+    return state?.telegram?.byUser?.[userId] ?? {};
+  }),
+  selectOrderedChats: vi.fn(() => []),
+  selectCurrentUser: vi.fn(() => null),
+}));
+
+// Mock the skills module
+vi.mock("../skills", () => ({
+  useExtraToolDefinition: {
+    name: "use_extra_tool",
+    description: "meta",
+    inputSchema: { type: "object", properties: {} },
+  },
+  executeUseExtraTool: vi.fn(),
+  executeExtraToolIfExists: vi.fn(() => null),
+  getAllExtraTools: vi.fn(() => []),
+  isExtraToolByName: vi.fn(() => false),
+}));
+
+// Mock rateLimiter
+vi.mock("../rateLimiter", () => ({
+  enforceRateLimit: vi.fn().mockResolvedValue(undefined),
+  resetRequestCallCount: vi.fn(),
+  isStateOnlyTool: vi.fn(() => false),
+  classifyTool: vi.fn(() => "api_read"),
+  isHeavyTool: vi.fn(() => false),
+}));
+
+// Mock logger
+vi.mock("../logger", () => ({
+  mcpLog: vi.fn(),
+  mcpWarn: vi.fn(),
+}));
+
+// Mock API functions used by tool handlers
+vi.mock("./api/getChats", () => ({
+  getChats: vi.fn(() =>
+    Promise.resolve({
+      data: [
+        {
+          id: "1",
+          title: "Chat One",
+          type: "private",
+          unreadCount: 0,
+          isPinned: false,
+        },
+        {
+          id: "2",
+          title: "Group Chat",
+          type: "group",
+          unreadCount: 5,
+          isPinned: true,
+        },
+      ],
+      fromCache: true,
+    }),
+  ),
+}));
+
+vi.mock("./api/sendMessage", () => ({
+  sendMessage: vi.fn(() =>
+    Promise.resolve({
+      data: { id: "msg1", message: "Hello", chatId: "1", date: 1234567890 },
+      fromCache: false,
+    }),
+  ),
+}));
+
+vi.mock("./api/getCurrentUser", () => ({
+  getCurrentUser: vi.fn(() =>
+    Promise.resolve({
+      data: {
+        id: "1",
+        firstName: "Alice",
+        lastName: "Smith",
+        username: "alice",
+        isBot: false,
+      },
+      fromCache: true,
+    }),
+  ),
+}));
+
+vi.mock("./api/getMessages", () => ({
+  getMessages: vi.fn(() =>
+    Promise.resolve({
+      data: [
+        {
+          id: "m1",
+          message: "First message",
+          chatId: "1",
+          date: 1234567890,
+          fromId: "100",
+        },
+        {
+          id: "m2",
+          message: "Second message",
+          chatId: "1",
+          date: 1234567891,
+          fromId: "200",
+        },
+      ],
+      fromCache: true,
+    }),
+  ),
+}));
+
+vi.mock("./api/helpers", async (importOriginal) => {
+  const original = (await importOriginal()) as any;
+  return {
+    ...original,
+    getChatById: vi.fn(() => ({
+      id: "1",
+      title: "Chat One",
+      type: "private",
+      unreadCount: 0,
+      isPinned: false,
+    })),
+    getOrderedChats: vi.fn(() => []),
+  };
+});
+
+// Helper: extract emitted data for a given event name
+function getEmittedResult(eventName: string): MCPToolResult | undefined {
+  const emitCall = mockTransportEmit.mock.calls.find(
+    (call: any[]) => call[0] === eventName,
+  );
+  return emitCall?.[1]?.result;
+}
+
+function getEmittedPayload(eventName: string): any {
+  const emitCall = mockTransportEmit.mock.calls.find(
+    (call: any[]) => call[0] === eventName,
+  );
+  return emitCall?.[1];
+}
+
+describe("TelegramMCPServer", () => {
+  let toolCallHandler: Function;
+  let listToolsHandler: Function;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+
+    // Re-apply mock implementations (mockReset: true in config clears them between tests)
+    const { SocketIOMCPTransportImpl } = await import("../transport");
+    vi.mocked(SocketIOMCPTransportImpl).mockImplementation(function (this: any) {
+      this.on = mockTransportOn;
+      this.off = mockTransportOff;
+      this.emit = mockTransportEmit;
+      this.updateSocket = mockTransportUpdateSocket;
+      this.connected = true;
+      return this;
+    } as any);
+
+    const rateLimiter = await import("../rateLimiter");
+    vi.mocked(rateLimiter.enforceRateLimit).mockResolvedValue(undefined);
+    vi.mocked(rateLimiter.resetRequestCallCount).mockImplementation(() => {});
+    vi.mocked(rateLimiter.isStateOnlyTool).mockReturnValue(false);
+
+    const skills = await import("../skills");
+    vi.mocked(skills.executeExtraToolIfExists).mockReturnValue(null as any);
+    vi.mocked(skills.getAllExtraTools).mockReturnValue([]);
+    vi.mocked(skills.isExtraToolByName).mockReturnValue(false);
+
+    // Re-apply API mocks
+    const getChatsApi = await import("./api/getChats");
+    vi.mocked(getChatsApi.getChats).mockResolvedValue({
+      data: [
+        { id: "1", title: "Chat One", type: "private", unreadCount: 0, isPinned: false },
+        { id: "2", title: "Group Chat", type: "group", unreadCount: 5, isPinned: true },
+      ],
+      fromCache: true,
+    });
+
+    const sendMsgApi = await import("./api/sendMessage");
+    vi.mocked(sendMsgApi.sendMessage).mockResolvedValue({
+      data: { id: "msg1", message: "Hello", chatId: "1", date: 1234567890 } as any,
+      fromCache: false,
+    });
+
+    const getUserApi = await import("./api/getCurrentUser");
+    vi.mocked(getUserApi.getCurrentUser).mockResolvedValue({
+      data: { id: "1", firstName: "Alice", lastName: "Smith", username: "alice", isBot: false } as any,
+      fromCache: true,
+    });
+
+    const getMsgsApi = await import("./api/getMessages");
+    vi.mocked(getMsgsApi.getMessages).mockResolvedValue({
+      data: [
+        { id: "m1", message: "First message", chatId: "1", date: 1234567890, fromId: "100" } as any,
+        { id: "m2", message: "Second message", chatId: "1", date: 1234567891, fromId: "200" } as any,
+      ],
+      fromCache: true,
+    });
+
+    const helpers = await import("./api/helpers");
+    vi.mocked(helpers.getChatById).mockReturnValue({
+      id: "1", title: "Chat One", type: "private", unreadCount: 0, isPinned: false,
+    });
+
+    const store = await import("../../../store");
+    vi.mocked(store.store.getState).mockReturnValue({
+      user: { user: { _id: "u1" } },
+      telegram: {
+        byUser: {
+          u1: {
+            connectionStatus: "connected",
+            authStatus: "authenticated",
+            isInitialized: true,
+            chats: {},
+            chatsOrder: [],
+            messages: {},
+            messagesOrder: {},
+            currentUser: null,
+          },
+        },
+      },
+    } as any);
+
+    // Import server after all mocks are set up
+    const { TelegramMCPServer } = await import("./server");
+
+    // Create server instance — constructor calls setupHandlers() which calls
+    // transport.on("toolCall", ...) and transport.on("listTools", ...)
+    new TelegramMCPServer(null);
+
+    // Extract the registered event handlers from transport.on calls
+    const onCalls = mockTransportOn.mock.calls;
+    const toolCallEntry = onCalls.find(
+      (call: any[]) => call[0] === "toolCall",
+    );
+    const listToolsEntry = onCalls.find(
+      (call: any[]) => call[0] === "listTools",
+    );
+
+    toolCallHandler = toolCallEntry![1];
+    listToolsHandler = listToolsEntry![1];
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe("listTools", () => {
+    it("should return array of available tools with correct shape", () => {
+      listToolsHandler({ requestId: "list-req-1" });
+
+      const payload = getEmittedPayload("listToolsResponse");
+      expect(payload).toBeDefined();
+      expect(payload.requestId).toBe("list-req-1");
+
+      const tools = payload.tools;
+      expect(Array.isArray(tools)).toBe(true);
+      expect(tools.length).toBeGreaterThan(50);
+
+      // Verify each tool has required properties
+      tools.forEach((tool: any) => {
+        expect(tool).toHaveProperty("name");
+        expect(tool).toHaveProperty("description");
+        expect(tool).toHaveProperty("inputSchema");
+        expect(typeof tool.name).toBe("string");
+        expect(typeof tool.description).toBe("string");
+        expect(typeof tool.inputSchema).toBe("object");
+      });
+    });
+
+    it("should include common tools like get_chats, send_message, get_me", () => {
+      listToolsHandler({ requestId: "list-req-2" });
+
+      const payload = getEmittedPayload("listToolsResponse");
+      const toolNames = payload.tools.map((t: any) => t.name);
+
+      expect(toolNames).toContain("get_chats");
+      expect(toolNames).toContain("send_message");
+      expect(toolNames).toContain("get_me");
+      expect(toolNames).toContain("get_messages");
+    });
+  });
+
+  describe("Tool execution - get_chats", () => {
+    it("should successfully execute get_chats and return chat list", async () => {
+      await toolCallHandler({
+        requestId: "req-1",
+        toolCall: { name: "get_chats", arguments: {} },
+      });
+
+      // Allow any microtasks to settle
+      await vi.waitFor(() => {
+        expect(mockTransportEmit).toHaveBeenCalledWith(
+          "toolResult",
+          expect.objectContaining({ requestId: "req-1" }),
+        );
+      });
+
+      const result = getEmittedResult("toolResult");
+      expect(result).toBeDefined();
+      expect(result!.isError).not.toBe(true);
+      expect(result!.content).toBeDefined();
+      expect(result!.content.length).toBeGreaterThan(0);
+
+      const contentText = JSON.stringify(result!.content);
+      expect(contentText).toContain("Chat One");
+    });
+
+    it("should execute get_chats with limit parameter", async () => {
+      await toolCallHandler({
+        requestId: "req-2",
+        toolCall: { name: "get_chats", arguments: { page_size: 1 } },
+      });
+
+      await vi.waitFor(() => {
+        expect(mockTransportEmit).toHaveBeenCalled();
+      });
+
+      const result = getEmittedResult("toolResult");
+      expect(result).toBeDefined();
+      expect(result!.isError).not.toBe(true);
+    });
+  });
+
+  describe("Tool execution - send_message", () => {
+    it("should successfully send a message", async () => {
+      await toolCallHandler({
+        requestId: "req-3",
+        toolCall: {
+          name: "send_message",
+          arguments: { chat_id: "1", message: "Hello from test" },
+        },
+      });
+
+      await vi.waitFor(() => {
+        expect(mockTransportEmit).toHaveBeenCalled();
+      });
+
+      const result = getEmittedResult("toolResult");
+      expect(result).toBeDefined();
+      expect(result!.isError).not.toBe(true);
+      expect(result!.content).toBeDefined();
+    });
+
+    it("should fail when chat_id is missing", async () => {
+      await toolCallHandler({
+        requestId: "req-4",
+        toolCall: {
+          name: "send_message",
+          arguments: { message: "Hello without chat_id" },
+        },
+      });
+
+      await vi.waitFor(() => {
+        expect(mockTransportEmit).toHaveBeenCalled();
+      });
+
+      const result = getEmittedResult("toolResult");
+      expect(result).toBeDefined();
+      expect(result!.isError).toBe(true);
+    });
+
+    it("should fail when text is missing", async () => {
+      await toolCallHandler({
+        requestId: "req-5",
+        toolCall: {
+          name: "send_message",
+          arguments: { chat_id: "1" },
+        },
+      });
+
+      await vi.waitFor(() => {
+        expect(mockTransportEmit).toHaveBeenCalled();
+      });
+
+      const result = getEmittedResult("toolResult");
+      expect(result).toBeDefined();
+      expect(result!.isError).toBe(true);
+    });
+  });
+
+  describe("Tool execution - get_me", () => {
+    it("should return current user information", async () => {
+      await toolCallHandler({
+        requestId: "req-6",
+        toolCall: { name: "get_me", arguments: {} },
+      });
+
+      await vi.waitFor(() => {
+        expect(mockTransportEmit).toHaveBeenCalled();
+      });
+
+      const result = getEmittedResult("toolResult");
+      expect(result).toBeDefined();
+      expect(result!.isError).not.toBe(true);
+      expect(result!.content).toBeDefined();
+
+      const contentText = JSON.stringify(result!.content);
+      expect(contentText).toContain("Alice");
+    });
+  });
+
+  describe("Tool execution - get_messages", () => {
+    it("should successfully retrieve messages from a chat", async () => {
+      await toolCallHandler({
+        requestId: "req-7",
+        toolCall: { name: "get_messages", arguments: { chat_id: "1" } },
+      });
+
+      await vi.waitFor(() => {
+        expect(mockTransportEmit).toHaveBeenCalled();
+      });
+
+      const result = getEmittedResult("toolResult");
+      expect(result).toBeDefined();
+      expect(result!.isError).not.toBe(true);
+      expect(result!.content).toBeDefined();
+    });
+  });
+
+  describe("Error handling", () => {
+    it("should return error for unknown tool", async () => {
+      await toolCallHandler({
+        requestId: "req-8",
+        toolCall: { name: "unknown_tool", arguments: {} },
+      });
+
+      await vi.waitFor(() => {
+        expect(mockTransportEmit).toHaveBeenCalled();
+      });
+
+      const result = getEmittedResult("toolResult");
+      expect(result).toBeDefined();
+      expect(result!.isError).toBe(true);
+
+      const errorText = JSON.stringify(result!.content).toLowerCase();
+      expect(errorText).toContain("unknown_tool");
+      expect(errorText).toMatch(/not found/);
+    });
+
+    it("should handle rate limit errors", async () => {
+      // Mock enforceRateLimit to reject for this call
+      const rateLimiter = await import("../rateLimiter");
+      vi.mocked(rateLimiter.enforceRateLimit).mockRejectedValueOnce(
+        new Error("Rate limit exceeded"),
+      );
+
+      await toolCallHandler({
+        requestId: "req-9",
+        toolCall: {
+          name: "send_message",
+          arguments: { chat_id: "1", message: "Test message" },
+        },
+      });
+
+      await vi.waitFor(() => {
+        expect(mockTransportEmit).toHaveBeenCalled();
+      });
+
+      const result = getEmittedResult("toolResult");
+      expect(result).toBeDefined();
+      expect(result!.isError).toBe(true);
+
+      const errorText = JSON.stringify(result!.content).toLowerCase();
+      expect(errorText).toMatch(/rate limit/);
+    });
+
+    it("should handle API errors gracefully", async () => {
+      // Make the send_message tool handler throw
+      const sendMessageApi = await import("./api/sendMessage");
+      vi.mocked(sendMessageApi.sendMessage).mockRejectedValueOnce(
+        new Error("Network error: Connection timeout"),
+      );
+
+      await toolCallHandler({
+        requestId: "req-10",
+        toolCall: {
+          name: "send_message",
+          arguments: { chat_id: "1", message: "Test" },
+        },
+      });
+
+      await vi.waitFor(() => {
+        expect(mockTransportEmit).toHaveBeenCalled();
+      });
+
+      const result = getEmittedResult("toolResult");
+      expect(result).toBeDefined();
+      expect(result!.isError).toBe(true);
+    });
+  });
+
+  describe("Transport integration", () => {
+    it("should register event handlers on construction", () => {
+      expect(mockTransportOn).toHaveBeenCalledWith(
+        "toolCall",
+        expect.any(Function),
+      );
+      expect(mockTransportOn).toHaveBeenCalledWith(
+        "listTools",
+        expect.any(Function),
+      );
+    });
+
+    it("should emit toolResult with correct requestId", async () => {
+      const requestId = "unique-req-id-123";
+
+      await toolCallHandler({
+        requestId,
+        toolCall: { name: "get_chats", arguments: {} },
+      });
+
+      await vi.waitFor(() => {
+        expect(mockTransportEmit).toHaveBeenCalledWith(
+          "toolResult",
+          expect.objectContaining({ requestId }),
+        );
+      });
+    });
+
+    it("should emit listToolsResponse with correct requestId", () => {
+      const requestId = "list-unique-123";
+
+      listToolsHandler({ requestId });
+
+      expect(mockTransportEmit).toHaveBeenCalledWith(
+        "listToolsResponse",
+        expect.objectContaining({ requestId }),
+      );
+    });
+  });
+});
diff --git a/src/lib/mcp/telegram/server.ts b/src/lib/mcp/telegram/server.ts
index 9d2ff0be9..417bc36f1 100644
--- a/src/lib/mcp/telegram/server.ts
+++ b/src/lib/mcp/telegram/server.ts
@@ -18,7 +18,11 @@ import { ErrorCategory, logAndFormatError } from "../errorHandler";
 import { ValidationError } from "../validation";
 import { SocketIOMCPTransportImpl } from "../transport";
 import { mcpLog } from "../logger";
-import { enforceRateLimit, resetRequestCallCount } from "../rateLimiter";
+import {
+  enforceRateLimit,
+  resetRequestCallCount,
+  isStateOnlyTool,
+} from "../rateLimiter";
 import {
   useExtraToolDefinition,
   executeUseExtraTool,
@@ -182,10 +186,15 @@ export class TelegramMCPServer {
       selectTelegramUserState(store.getState());
 
     try {
-      return await toolHandler(args, {
+      const result = await toolHandler(args, {
         telegramState,
         transport: this.transport,
       });
+      // Auto-infer fromCache if the tool didn't set it explicitly
+      if (result.fromCache === undefined) {
+        result.fromCache = isStateOnlyTool(name);
+      }
+      return result;
     } catch (error) {
       if (error instanceof ValidationError) {
         return logAndFormatError(name, error, ErrorCategory.VALIDATION);
diff --git a/src/lib/mcp/telegram/telegramApi.ts b/src/lib/mcp/telegram/telegramApi.ts
deleted file mode 100644
index 4da527918..000000000
--- a/src/lib/mcp/telegram/telegramApi.ts
+++ /dev/null
@@ -1,488 +0,0 @@
-/**
- * Telegram API helpers for MCP tools
- * Uses mtprotoService + Redux telegram state (alphahuman)
- *
- * "WithApiFallback" variants try cached Redux state first, then call the
- * Telegram API when cache is empty. They call enforceRateLimit() internally
- * before any API call so the fast cache path stays unthrottled.
- */
-
-import { store } from "../../../store";
-import { mtprotoService } from "../../../services/mtprotoService";
-import {
-  selectOrderedChats,
-  selectCurrentUser,
-  selectTelegramUserState,
-} from "../../../store/telegramSelectors";
-import type {
-  TelegramChat,
-  TelegramUser,
-  TelegramMessage,
-} from "../../../store/telegram/types";
-import { Api } from "telegram";
-import bigInt from "big-integer";
-import { enforceRateLimit } from "../rateLimiter";
-
-function getTelegramState() {
-  return selectTelegramUserState(store.getState());
-}
-
-export interface FormattedEntity {
-  id: string;
-  name: string;
-  type: string;
-  username?: string;
-  phone?: string;
-}
-
-export interface FormattedMessage {
-  id: number | string;
-  date: string;
-  text: string;
-  from_id?: string;
-  has_media?: boolean;
-  media_type?: string;
-}
-
-/**
- * Get chat by ID or username
- */
-export function getChatById(chatId: string | number): TelegramChat | undefined {
-  const state = getTelegramState();
-  const idStr = String(chatId);
-
-  const chat = state.chats[idStr];
-  if (chat) return chat;
-
-  if (
-    typeof chatId === "string" &&
-    (chatId.startsWith("@") || /^[a-zA-Z0-9_]+$/.test(chatId))
-  ) {
-    const username = chatId.startsWith("@") ? chatId : `@${chatId}`;
-    return Object.values(state.chats).find(
-      (c) =>
-        c.username &&
-        (c.username === username || c.username === username.slice(1)),
-    );
-  }
-
-  return undefined;
-}
-
-/**
- * Get user by ID (current user only for now; no full user cache)
- */
-export function getUserById(userId: string | number): TelegramUser | undefined {
-  const state = getTelegramState();
-  const current = state.currentUser;
-  if (!current) return undefined;
-  if (String(current.id) === String(userId)) return current;
-  return undefined;
-}
-
-/**
- * Get messages from a chat (from store cache)
- * @param offset - numeric offset for pagination (default 0)
- */
-export async function getMessages(
-  chatId: string | number,
-  limit = 20,
-  offset = 0,
-): Promise<TelegramMessage[] | undefined> {
-  const chat = getChatById(chatId);
-  if (!chat) return undefined;
-
-  const state = getTelegramState();
-  const order = state.messagesOrder[chat.id] ?? [];
-  const byId = state.messages[chat.id] ?? {};
-  const all = order.map((id) => byId[id]).filter(Boolean);
-  const list = all.slice(offset, offset + limit);
-
-  return list.length ? list : undefined;
-}
-
-/**
- * Send a message to a chat
- */
-export async function sendMessage(
-  chatId: string | number,
-  message: string,
-  replyToMessageId?: number,
-): Promise<{ id: string } | undefined> {
-  const chat = getChatById(chatId);
-  if (!chat) return undefined;
-
-  const entity = chat.username ? `@${chat.username.replace("@", "")}` : chat.id;
-
-  if (replyToMessageId !== undefined) {
-    const client = mtprotoService.getClient();
-    await mtprotoService.withFloodWaitHandling(async () => {
-      await client.sendMessage(entity, {
-        message,
-        replyTo: replyToMessageId,
-      });
-    });
-  } else {
-    await mtprotoService.sendMessage(entity, message);
-  }
-
-  return { id: String(Date.now()) };
-}
-
-/**
- * Get list of chats (from store)
- */
-export async function getChats(limit = 20): Promise<TelegramChat[]> {
-  const state = store.getState();
-  const ordered = selectOrderedChats(state);
-  return ordered.slice(0, limit);
-}
-
-/**
- * Search chats by query (filter by title/username from store)
- */
-export async function searchChats(query: string): Promise<TelegramChat[]> {
-  const state = store.getState();
-  const ordered = selectOrderedChats(state);
-  const q = query.toLowerCase();
-  return ordered.filter((c) => {
-    const title = (c.title ?? "").toLowerCase();
-    const un = (c.username ?? "").toLowerCase();
-    return title.includes(q) || un.includes(q);
-  });
-}
-
-/**
- * Get current user info
- */
-export function getCurrentUser(): TelegramUser | undefined {
-  const state = store.getState();
-  return selectCurrentUser(state) ?? undefined;
-}
-
-/**
- * Format entity (chat or user) for display
- */
-export function formatEntity(
-  entity: TelegramChat | TelegramUser,
-): FormattedEntity {
-  if ("title" in entity) {
-    const chat = entity as TelegramChat;
-    const type =
-      chat.type === "channel"
-        ? "channel"
-        : chat.type === "supergroup"
-          ? "group"
-          : chat.type;
-    return {
-      id: chat.id,
-      name: chat.title ?? "Unknown",
-      type,
-      username: chat.username,
-    };
-  }
-  const user = entity as TelegramUser;
-  const name =
-    [user.firstName, user.lastName].filter(Boolean).join(" ") || "Unknown";
-  return {
-    id: user.id,
-    name,
-    type: "user",
-    username: user.username,
-    phone: user.phoneNumber,
-  };
-}
-
-/**
- * Format message for display
- */
-export function formatMessage(message: TelegramMessage): FormattedMessage {
-  const result: FormattedMessage = {
-    id: message.id,
-    date: new Date(message.date * 1000).toISOString(),
-    text: message.message ?? "",
-  };
-  if (message.fromId) result.from_id = message.fromId;
-  if (message.media?.type) {
-    result.has_media = true;
-    result.media_type = message.media.type;
-  }
-  return result;
-}
-
-// ---------------------------------------------------------------------------
-// API Fallback helpers
-// ---------------------------------------------------------------------------
-
-/** Convert a raw GramJS message to our TelegramMessage format */
-function apiMessageToTelegramMessage(
-  msg: Record<string, unknown>,
-  chatId: string,
-): TelegramMessage {
-  const fromId =
-    msg.fromId && typeof msg.fromId === "object" && "userId" in (msg.fromId as object)
-      ? String((msg.fromId as { userId: unknown }).userId)
-      : undefined;
-
-  const replyTo = msg.replyTo as { replyToMsgId?: number } | undefined;
-
-  const media = msg.media as { className?: string } | undefined;
-  let mediaInfo: TelegramMessage["media"] | undefined;
-  if (media && media.className && media.className !== "MessageMediaEmpty") {
-    mediaInfo = { type: media.className };
-  }
-
-  return {
-    id: String(msg.id ?? ""),
-    chatId,
-    date: typeof msg.date === "number" ? msg.date : 0,
-    message: typeof msg.message === "string" ? msg.message : "",
-    fromId,
-    isOutgoing: Boolean(msg.out),
-    isEdited: msg.editDate != null,
-    isForwarded: msg.fwdFrom != null,
-    replyToMessageId: replyTo?.replyToMsgId != null
-      ? String(replyTo.replyToMsgId)
-      : undefined,
-    media: mediaInfo,
-  };
-}
-
-/**
- * Get messages — tries cached Redux state first, falls back to Telegram API.
- * Calls enforceRateLimit() internally before any API call.
- */
-export async function getMessagesWithApiFallback(
-  chatId: string | number,
-  limit = 20,
-  offset = 0,
-): Promise<TelegramMessage[] | undefined> {
-  // 1. Try cache
-  const cached = await getMessages(chatId, limit, offset);
-  if (cached && cached.length > 0) return cached;
-
-  // 2. Resolve chat for API call
-  const chat = getChatById(chatId);
-  if (!chat) return undefined;
-
-  // 3. Rate limit before API call
-  try {
-    await enforceRateLimit("__api_fallback_messages");
-  } catch {
-    return undefined; // Rate limited — return nothing rather than error
-  }
-
-  // 4. Fetch from Telegram API
-  try {
-    const client = mtprotoService.getClient();
-    const entity = chat.username ? chat.username : chat.id;
-    const inputPeer = await client.getInputEntity(entity);
-
-    const result = await mtprotoService.withFloodWaitHandling(async () => {
-      return client.invoke(
-        new Api.messages.GetHistory({
-          peer: inputPeer,
-          offsetId: 0,
-          offsetDate: 0,
-          addOffset: offset,
-          limit,
-          maxId: 0,
-          minId: 0,
-          hash: bigInt(0),
-        }),
-      );
-    });
-
-    if ("messages" in result && Array.isArray(result.messages)) {
-      const messages = (result.messages as unknown as Record<string, unknown>[])
-        .filter((m) => m.className !== "MessageEmpty")
-        .map((m) => apiMessageToTelegramMessage(m, chat.id));
-
-      // Enrich fromName from users list
-      if ("users" in result && Array.isArray(result.users)) {
-        const usersById = new Map<string, string>();
-        for (const u of result.users as Array<{
-          id?: unknown;
-          firstName?: string;
-          lastName?: string;
-        }>) {
-          if (u.id != null) {
-            const name =
-              [u.firstName, u.lastName].filter(Boolean).join(" ") || "Unknown";
-            usersById.set(String(u.id), name);
-          }
-        }
-        for (const msg of messages) {
-          if (msg.fromId && !msg.fromName) {
-            msg.fromName = usersById.get(msg.fromId);
-          }
-        }
-      }
-
-      return messages.length > 0 ? messages : undefined;
-    }
-  } catch {
-    // API failed — return nothing
-  }
-
-  return undefined;
-}
-
-/** Convert a raw GramJS dialog + chat/user to our TelegramChat format */
-function apiDialogToTelegramChat(
-  dialog: Record<string, unknown>,
-  chatsById: Map<string, Record<string, unknown>>,
-  usersById: Map<string, Record<string, unknown>>,
-): TelegramChat | undefined {
-  const peer = dialog.peer as { className?: string; userId?: unknown; chatId?: unknown; channelId?: unknown } | undefined;
-  if (!peer) return undefined;
-
-  let id: string;
-  let type: TelegramChat["type"];
-  let raw: Record<string, unknown> | undefined;
-
-  if (peer.className === "PeerUser" && peer.userId != null) {
-    id = String(peer.userId);
-    type = "private";
-    raw = usersById.get(id);
-  } else if (peer.className === "PeerChat" && peer.chatId != null) {
-    id = String(peer.chatId);
-    type = "group";
-    raw = chatsById.get(id);
-  } else if (peer.className === "PeerChannel" && peer.channelId != null) {
-    id = String(peer.channelId);
-    raw = chatsById.get(id);
-    type = raw && Boolean(raw.megagroup) ? "supergroup" : "channel";
-  } else {
-    return undefined;
-  }
-
-  let title: string;
-  let username: string | undefined;
-  if (raw) {
-    title =
-      (raw.title as string) ??
-      [raw.firstName, raw.lastName].filter(Boolean).join(" ") ??
-      "Unknown";
-    username = raw.username as string | undefined;
-  } else {
-    title = "Unknown";
-  }
-
-  return {
-    id,
-    title,
-    type,
-    username,
-    unreadCount: typeof dialog.unreadCount === "number" ? dialog.unreadCount : 0,
-    isPinned: Boolean(dialog.pinned),
-  };
-}
-
-/**
- * Get chats — tries cached Redux state first, falls back to Telegram API.
- * Calls enforceRateLimit() internally before any API call.
- */
-export async function getChatsWithApiFallback(
-  limit = 20,
-): Promise<TelegramChat[]> {
-  // 1. Try cache
-  const cached = await getChats(limit);
-  if (cached.length > 0) return cached;
-
-  // 2. Rate limit before API call
-  try {
-    await enforceRateLimit("__api_fallback_chats");
-  } catch {
-    return [];
-  }
-
-  // 3. Fetch from Telegram API
-  try {
-    const client = mtprotoService.getClient();
-
-    const result = await mtprotoService.withFloodWaitHandling(async () => {
-      return client.invoke(
-        new Api.messages.GetDialogs({
-          offsetDate: 0,
-          offsetId: 0,
-          offsetPeer: new Api.InputPeerEmpty(),
-          limit,
-          hash: bigInt(0),
-        }),
-      );
-    });
-
-    if (!("dialogs" in result) || !Array.isArray(result.dialogs)) return [];
-
-    // Index chats and users by ID
-    const chatsById = new Map<string, Record<string, unknown>>();
-    const usersById = new Map<string, Record<string, unknown>>();
-    if ("chats" in result && Array.isArray(result.chats)) {
-      for (const c of result.chats as unknown as Record<string, unknown>[]) {
-        if (c.id != null) chatsById.set(String(c.id), c);
-      }
-    }
-    if ("users" in result && Array.isArray(result.users)) {
-      for (const u of result.users as unknown as Record<string, unknown>[]) {
-        if (u.id != null) usersById.set(String(u.id), u);
-      }
-    }
-
-    return (result.dialogs as unknown as Record<string, unknown>[])
-      .map((d) => apiDialogToTelegramChat(d, chatsById, usersById))
-      .filter((c): c is TelegramChat => c !== undefined)
-      .slice(0, limit);
-  } catch {
-    return [];
-  }
-}
-
-/**
- * Get current user — tries cached Redux state first, falls back to client.getMe().
- * Calls enforceRateLimit() internally before any API call.
- */
-export async function getCurrentUserWithApiFallback(): Promise<
-  TelegramUser | undefined
-> {
-  // 1. Try cache
-  const cached = getCurrentUser();
-  if (cached) return cached;
-
-  // 2. Rate limit before API call
-  try {
-    await enforceRateLimit("__api_fallback_me");
-  } catch {
-    return undefined;
-  }
-
-  // 3. Fetch from Telegram API
-  try {
-    const client = mtprotoService.getClient();
-    const me = await mtprotoService.withFloodWaitHandling(async () => {
-      return client.getMe();
-    });
-
-    if (!me) return undefined;
-
-    const raw = me as unknown as {
-      id?: unknown;
-      firstName?: string;
-      lastName?: string;
-      username?: string;
-      phone?: string;
-      bot?: boolean;
-    };
-
-    return {
-      id: String(raw.id ?? ""),
-      firstName: raw.firstName ?? "",
-      lastName: raw.lastName,
-      username: raw.username,
-      phoneNumber: raw.phone,
-      isBot: Boolean(raw.bot),
-    };
-  } catch {
-    return undefined;
-  }
-}
diff --git a/src/lib/mcp/telegram/tools/__tests__/getChats.test.ts b/src/lib/mcp/telegram/tools/__tests__/getChats.test.ts
new file mode 100644
index 000000000..f039f4aeb
--- /dev/null
+++ b/src/lib/mcp/telegram/tools/__tests__/getChats.test.ts
@@ -0,0 +1,153 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { getChats, tool } from "../getChats";
+import type { TelegramMCPContext } from "../../types";
+import type { TelegramState } from "../../../../../store/telegram/types";
+
+vi.mock("../../api/getChats");
+
+const { getChats: getChatsApi } = await import("../../api/getChats");
+
+describe("getChats tool handler", () => {
+  let mockContext: TelegramMCPContext;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockContext = {
+      telegramState: {
+        byUser: {},
+        currentUserId: null,
+      } as unknown as TelegramState,
+      transport: {
+        emit: vi.fn(),
+        on: vi.fn(),
+        off: vi.fn(),
+      } as any,
+    };
+  });
+
+  it("should return formatted chat list with IDs and titles", async () => {
+    const mockChats = [
+      { id: "123", title: "Tech Group", type: "group" as const, unreadCount: 0, isPinned: false },
+      { id: "456", title: "Trading Chat", type: "group" as const, unreadCount: 0, isPinned: false },
+      { id: "789", title: "John Doe", type: "private" as const, unreadCount: 0, isPinned: false },
+    ];
+
+    vi.mocked(getChatsApi).mockResolvedValue({
+      data: mockChats,
+      fromCache: false,
+    });
+
+    const result = await getChats({}, mockContext);
+
+    expect(result.isError).toBeFalsy();
+    expect(result.content[0].text).toContain("123");
+    expect(result.content[0].text).toContain("Tech Group");
+    expect(result.content[0].text).toContain("456");
+    expect(result.content[0].text).toContain("Trading Chat");
+    expect(result.content[0].text).toContain("789");
+    expect(result.content[0].text).toContain("John Doe");
+  });
+
+  it("should handle empty chat list", async () => {
+    vi.mocked(getChatsApi).mockResolvedValue({
+      data: [],
+      fromCache: false,
+    });
+
+    const result = await getChats({}, mockContext);
+
+    expect(result.isError).toBeFalsy();
+    expect(result.content[0].text).toContain("Page out of range");
+  });
+
+  it("should return error for empty page", async () => {
+    const mockChats = [
+      { id: "123", title: "Chat 1", type: "private" as const, unreadCount: 0, isPinned: false },
+      { id: "456", title: "Chat 2", type: "private" as const, unreadCount: 0, isPinned: false },
+    ];
+
+    vi.mocked(getChatsApi).mockResolvedValue({
+      data: mockChats,
+      fromCache: false,
+    });
+
+    const result = await getChats(
+      { page: 5, page_size: 10 },
+      mockContext
+    );
+
+    expect(result.content[0].text).toContain("Page out of range");
+  });
+
+  it("should handle pagination with page 2 and page_size 2", async () => {
+    const mockChats = [
+      { id: "1", title: "Chat 1", type: "private" as const, unreadCount: 0, isPinned: false },
+      { id: "2", title: "Chat 2", type: "private" as const, unreadCount: 0, isPinned: false },
+      { id: "3", title: "Chat 3", type: "private" as const, unreadCount: 0, isPinned: false },
+      { id: "4", title: "Chat 4", type: "private" as const, unreadCount: 0, isPinned: false },
+      { id: "5", title: "Chat 5", type: "private" as const, unreadCount: 0, isPinned: false },
+    ];
+
+    vi.mocked(getChatsApi).mockResolvedValue({
+      data: mockChats,
+      fromCache: false,
+    });
+
+    const result = await getChats(
+      { page: 2, page_size: 2 },
+      mockContext
+    );
+
+    expect(result.isError).toBeFalsy();
+    const text = result.content[0].text;
+    expect(text).toContain("3");
+    expect(text).toContain("Chat 3");
+    expect(text).toContain("4");
+    expect(text).toContain("Chat 4");
+    expect(text).not.toContain("Chat 1");
+    expect(text).not.toContain("Chat 5");
+  });
+
+  it("should use default pagination values", async () => {
+    const mockChats = Array.from({ length: 25 }, (_, i) => ({
+      id: String(i + 1),
+      title: `Chat ${i + 1}`,
+      type: "private" as const,
+      unreadCount: 0,
+      isPinned: false,
+    }));
+
+    vi.mocked(getChatsApi).mockResolvedValue({
+      data: mockChats,
+      fromCache: false,
+    });
+
+    const result = await getChats({}, mockContext);
+
+    expect(result.isError).toBeFalsy();
+    const text = result.content[0].text;
+    // Default page_size should be 20
+    expect(text).toContain("Chat 1");
+    expect(text).toContain("Chat 20");
+    expect(text).not.toContain("Chat 21");
+  });
+
+  it("should handle API errors gracefully", async () => {
+    vi.mocked(getChatsApi).mockRejectedValue(
+      new Error("Failed to fetch chats")
+    );
+
+    const result = await getChats({}, mockContext);
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain("CHAT-ERR");
+  });
+
+  it("should include tool definition with correct schema", () => {
+    expect(tool.name).toBe("get_chats");
+    expect(tool.description).toContain("chats");
+    expect(tool.inputSchema.type).toBe("object");
+    expect(tool.inputSchema.properties).toHaveProperty("page");
+    expect(tool.inputSchema.properties).toHaveProperty("page_size");
+  });
+});
diff --git a/src/lib/mcp/telegram/tools/__tests__/getMe.test.ts b/src/lib/mcp/telegram/tools/__tests__/getMe.test.ts
new file mode 100644
index 000000000..9bdabc130
--- /dev/null
+++ b/src/lib/mcp/telegram/tools/__tests__/getMe.test.ts
@@ -0,0 +1,169 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { getMe, tool } from "../getMe";
+import type { TelegramMCPContext } from "../../types";
+import type { TelegramState } from "../../../../../store/telegram/types";
+
+vi.mock("../../api/getCurrentUser");
+
+const { getCurrentUser } = await import("../../api/getCurrentUser");
+
+describe("getMe tool handler", () => {
+  let mockContext: TelegramMCPContext;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockContext = {
+      telegramState: {
+        byUser: {},
+        currentUserId: null,
+      } as unknown as TelegramState,
+      transport: {
+        emit: vi.fn(),
+        on: vi.fn(),
+        off: vi.fn(),
+      } as any,
+    };
+  });
+
+  it("should return formatted user JSON with all fields", async () => {
+    const mockUser = {
+      id: "123456789",
+      firstName: "John",
+      lastName: "Doe",
+      username: "johndoe",
+      phoneNumber: "+1234567890",
+      isBot: false,
+    };
+
+    vi.mocked(getCurrentUser).mockResolvedValue({
+      data: mockUser,
+      fromCache: false,
+    });
+
+    const result = await getMe({}, mockContext);
+
+    expect(result.isError).toBeFalsy();
+    const text = result.content[0].text;
+    const parsed = JSON.parse(text);
+    expect(parsed.id).toBe("123456789");
+    expect(parsed.name).toBe("John Doe");
+    expect(parsed.username).toBe("johndoe");
+    expect(parsed.type).toBe("user");
+  });
+
+  it("should handle user without username", async () => {
+    const mockUser = {
+      id: "987654321",
+      firstName: "Jane",
+      lastName: "Smith",
+      username: undefined,
+      phoneNumber: "+9876543210",
+      isBot: false,
+    };
+
+    vi.mocked(getCurrentUser).mockResolvedValue({
+      data: mockUser,
+      fromCache: false,
+    });
+
+    const result = await getMe({}, mockContext);
+
+    expect(result.isError).toBeFalsy();
+    const text = result.content[0].text;
+    const parsed = JSON.parse(text);
+    expect(parsed.id).toBe("987654321");
+    expect(parsed.name).toBe("Jane Smith");
+    expect(parsed).not.toHaveProperty("username");
+    expect(parsed.type).toBe("user");
+  });
+
+  it("should handle user with only first name", async () => {
+    const mockUser = {
+      id: "111222333",
+      firstName: "Alice",
+      lastName: undefined,
+      username: "alice",
+      phoneNumber: "+1112223333",
+      isBot: false,
+    };
+
+    vi.mocked(getCurrentUser).mockResolvedValue({
+      data: mockUser,
+      fromCache: false,
+    });
+
+    const result = await getMe({}, mockContext);
+
+    expect(result.isError).toBeFalsy();
+    const text = result.content[0].text;
+    const parsed = JSON.parse(text);
+    expect(parsed.name).toBe("Alice");
+  });
+
+  it("should identify bot users correctly", async () => {
+    const mockUser = {
+      id: "999888777",
+      firstName: "Bot",
+      lastName: "Helper",
+      username: "helpbot",
+      phoneNumber: undefined,
+      isBot: true,
+    };
+
+    vi.mocked(getCurrentUser).mockResolvedValue({
+      data: mockUser,
+      fromCache: false,
+    });
+
+    const result = await getMe({}, mockContext);
+
+    expect(result.isError).toBeFalsy();
+    const text = result.content[0].text;
+    const parsed = JSON.parse(text);
+    // formatEntity always returns "user" for TelegramUser, doesn't check isBot
+    expect(parsed.type).toBe("user");
+    expect(parsed.id).toBe("999888777");
+  });
+
+  it("should return error when user is not available", async () => {
+    vi.mocked(getCurrentUser).mockResolvedValue({
+      data: undefined,
+      fromCache: false,
+    });
+
+    const result = await getMe({}, mockContext);
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain("User information not available");
+  });
+
+  it("should return error when user is null", async () => {
+    vi.mocked(getCurrentUser).mockResolvedValue({
+      data: null as any,
+      fromCache: false,
+    });
+
+    const result = await getMe({}, mockContext);
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain("User information not available");
+  });
+
+  it("should handle API errors gracefully", async () => {
+    vi.mocked(getCurrentUser).mockRejectedValue(
+      new Error("Failed to fetch user")
+    );
+
+    const result = await getMe({}, mockContext);
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain("PROFILE-ERR");
+  });
+
+  it("should include tool definition with correct schema", () => {
+    expect(tool.name).toBe("get_me");
+    expect(tool.description).toContain("user information");
+    expect(tool.inputSchema.type).toBe("object");
+    expect(tool.inputSchema.properties).toBeDefined();
+  });
+});
diff --git a/src/lib/mcp/telegram/tools/__tests__/getMessages.test.ts b/src/lib/mcp/telegram/tools/__tests__/getMessages.test.ts
new file mode 100644
index 000000000..650f2ceb5
--- /dev/null
+++ b/src/lib/mcp/telegram/tools/__tests__/getMessages.test.ts
@@ -0,0 +1,249 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { getMessages, tool } from "../getMessages";
+import type { TelegramMCPContext } from "../../types";
+import type { TelegramState } from "../../../../../store/telegram/types";
+
+vi.mock("../../api/getMessages");
+vi.mock("../../api/helpers", async (importOriginal) => {
+  const original = (await importOriginal()) as any;
+  return {
+    ...original,
+    getChatById: vi.fn(),
+    formatMessage: original.formatMessage,
+  };
+});
+
+const { getMessages: getMessagesApi } = await import("../../api/getMessages");
+const { getChatById } = await import("../../api/helpers");
+
+describe("getMessages tool handler", () => {
+  let mockContext: TelegramMCPContext;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockContext = {
+      telegramState: {
+        byUser: {},
+        currentUserId: null,
+      } as unknown as TelegramState,
+      transport: {
+        emit: vi.fn(),
+        on: vi.fn(),
+        off: vi.fn(),
+      } as any,
+    };
+  });
+
+  it("should return error when chat_id is missing", async () => {
+    const result = await getMessages({}, mockContext);
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain("chat_id");
+  });
+
+  it("should return error when chat is not found", async () => {
+    vi.mocked(getChatById).mockReturnValue(undefined);
+
+    const result = await getMessages(
+      { chat_id: "123456789" },
+      mockContext
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain("Chat not found: 123456789");
+  });
+
+  it("should return formatted messages with ID, sender, and date", async () => {
+    const mockChat = {
+      id: "123456789",
+      title: "Test Chat",
+    };
+
+    const mockMessages = [
+      {
+        id: "1",
+        chatId: "123456789",
+        fromId: "user1",
+        fromName: "User One",
+        message: "Hello!",
+        date: 1609459200,
+        isOutgoing: false,
+        isEdited: false,
+        isForwarded: false,
+      },
+      {
+        id: "2",
+        chatId: "123456789",
+        fromId: "user2",
+        fromName: "User Two",
+        message: "Hi there!",
+        date: 1609459260,
+        isOutgoing: false,
+        isEdited: false,
+        isForwarded: false,
+      },
+    ];
+
+    vi.mocked(getChatById).mockReturnValue(mockChat as any);
+    vi.mocked(getMessagesApi).mockResolvedValue({
+      data: mockMessages,
+      fromCache: false,
+    });
+
+    const result = await getMessages(
+      { chat_id: "123456789" },
+      mockContext
+    );
+
+    expect(result.isError).toBeFalsy();
+    const text = result.content[0].text;
+    expect(text).toContain("ID: 1");
+    expect(text).toContain("User One");
+    expect(text).toContain("Hello!");
+    expect(text).toContain("ID: 2");
+    expect(text).toContain("User Two");
+    expect(text).toContain("Hi there!");
+  });
+
+  it("should return message when no messages are found", async () => {
+    const mockChat = {
+      id: "123456789",
+      title: "Empty Chat",
+    };
+
+    vi.mocked(getChatById).mockReturnValue(mockChat as any);
+    vi.mocked(getMessagesApi).mockResolvedValue({
+      data: [],
+      fromCache: false,
+    });
+
+    const result = await getMessages(
+      { chat_id: "123456789" },
+      mockContext
+    );
+
+    expect(result.isError).toBeFalsy();
+    expect(result.content[0].text).toContain("No messages found for this page");
+  });
+
+  it("should handle pagination correctly", async () => {
+    const mockChat = {
+      id: "123456789",
+      title: "Test Chat",
+    };
+
+    const mockMessages = [
+      { id: "3", chatId: "123456789", fromId: "user3", message: "Message 3", date: 1609459300, isOutgoing: false, isEdited: false, isForwarded: false },
+      { id: "4", chatId: "123456789", fromId: "user4", message: "Message 4", date: 1609459400, isOutgoing: false, isEdited: false, isForwarded: false },
+    ];
+
+    vi.mocked(getChatById).mockReturnValue(mockChat as any);
+    vi.mocked(getMessagesApi).mockResolvedValue({
+      data: mockMessages,
+      fromCache: false,
+    });
+
+    const result = await getMessages(
+      { chat_id: "123456789", page: 2, page_size: 2 },
+      mockContext
+    );
+
+    expect(result.isError).toBeFalsy();
+    // validateId converts string to number
+    expect(getMessagesApi).toHaveBeenCalledWith(
+      123456789,
+      2,
+      2
+    );
+  });
+
+  it("should use default pagination values", async () => {
+    const mockChat = {
+      id: "123456789",
+      title: "Test Chat",
+    };
+
+    vi.mocked(getChatById).mockReturnValue(mockChat as any);
+    vi.mocked(getMessagesApi).mockResolvedValue({
+      data: [],
+      fromCache: false,
+    });
+
+    await getMessages({ chat_id: "123456789" }, mockContext);
+
+    // validateId converts string to number
+    expect(getMessagesApi).toHaveBeenCalledWith(
+      123456789,
+      20,
+      0
+    );
+  });
+
+  it("should handle messages without sender ID", async () => {
+    const mockChat = {
+      id: "123456789",
+      title: "Test Chat",
+    };
+
+    const mockMessages = [
+      {
+        id: "5",
+        chatId: "123456789",
+        fromId: undefined,
+        fromName: undefined,
+        message: "System message",
+        date: 1609459500,
+        isOutgoing: false,
+        isEdited: false,
+        isForwarded: false,
+      },
+    ];
+
+    vi.mocked(getChatById).mockReturnValue(mockChat as any);
+    vi.mocked(getMessagesApi).mockResolvedValue({
+      data: mockMessages,
+      fromCache: false,
+    });
+
+    const result = await getMessages(
+      { chat_id: "123456789" },
+      mockContext
+    );
+
+    expect(result.isError).toBeFalsy();
+    const text = result.content[0].text;
+    expect(text).toContain("ID: 5");
+    expect(text).toContain("Unknown");
+    expect(text).toContain("System message");
+  });
+
+  it("should handle API errors gracefully", async () => {
+    const mockChat = {
+      id: "123456789",
+      title: "Test Chat",
+    };
+
+    vi.mocked(getChatById).mockReturnValue(mockChat as any);
+    vi.mocked(getMessagesApi).mockRejectedValue(
+      new Error("Network error")
+    );
+
+    const result = await getMessages(
+      { chat_id: "123456789" },
+      mockContext
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain("MSG-ERR");
+  });
+
+  it("should include tool definition with correct schema", () => {
+    expect(tool.name).toBe("get_messages");
+    expect(tool.description).toContain("messages");
+    expect(tool.inputSchema.type).toBe("object");
+    expect(tool.inputSchema.properties).toHaveProperty("chat_id");
+    expect(tool.inputSchema.properties).toHaveProperty("page");
+    expect(tool.inputSchema.properties).toHaveProperty("page_size");
+    expect(tool.inputSchema.required).toContain("chat_id");
+  });
+});
diff --git a/src/lib/mcp/telegram/tools/__tests__/sendMessage.test.ts b/src/lib/mcp/telegram/tools/__tests__/sendMessage.test.ts
new file mode 100644
index 000000000..dea3969eb
--- /dev/null
+++ b/src/lib/mcp/telegram/tools/__tests__/sendMessage.test.ts
@@ -0,0 +1,136 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { sendMessage, tool } from "../sendMessage";
+import type { TelegramMCPContext } from "../../types";
+import type { TelegramState } from "../../../../../store/telegram/types";
+
+vi.mock("../../api/sendMessage");
+
+const { sendMessage: sendMessageApi } = await import("../../api/sendMessage");
+
+describe("sendMessage tool handler", () => {
+  let mockContext: TelegramMCPContext;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockContext = {
+      telegramState: {
+        byUser: {},
+        currentUserId: null,
+      } as unknown as TelegramState,
+      transport: {
+        emit: vi.fn(),
+        on: vi.fn(),
+        off: vi.fn(),
+      } as any,
+    };
+  });
+
+  it("should return error when chat_id is missing", async () => {
+    const result = await sendMessage(
+      { message: "test message" },
+      mockContext
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain("chat_id");
+  });
+
+  it("should return error when message is missing", async () => {
+    const result = await sendMessage(
+      { chat_id: "123456789" },
+      mockContext
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toBe("Message content is required");
+  });
+
+  it("should return error when message is empty string", async () => {
+    const result = await sendMessage(
+      { chat_id: "123456789", message: "" },
+      mockContext
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toBe("Message content is required");
+  });
+
+  it("should return error when message is non-string type", async () => {
+    const result = await sendMessage(
+      { chat_id: "123456789", message: 123 as any },
+      mockContext
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toBe("Message content is required");
+  });
+
+  it("should successfully send message", async () => {
+    vi.mocked(sendMessageApi).mockResolvedValue({
+      data: { id: "42" },
+      fromCache: false,
+    });
+
+    const result = await sendMessage(
+      {
+        chat_id: "123456789",
+        message: "Hello, world!",
+      },
+      mockContext
+    );
+
+    expect(result.isError).toBeFalsy();
+    expect(result.content[0].text).toBe("Message sent successfully.");
+    // validateId converts string to number
+    expect(sendMessageApi).toHaveBeenCalledWith(
+      123456789,
+      "Hello, world!"
+    );
+  });
+
+  it("should return error when API returns undefined", async () => {
+    vi.mocked(sendMessageApi).mockResolvedValue({
+      data: undefined,
+      fromCache: false,
+    });
+
+    const result = await sendMessage(
+      {
+        chat_id: "123456789",
+        message: "test",
+      },
+      mockContext
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain("Failed to send message");
+  });
+
+  it("should handle API errors gracefully", async () => {
+    vi.mocked(sendMessageApi).mockRejectedValue(
+      new Error("Network error")
+    );
+
+    const result = await sendMessage(
+      {
+        chat_id: "123456789",
+        message: "test",
+      },
+      mockContext
+    );
+
+    expect(result.isError).toBe(true);
+    // Error handler formats with error code
+    expect(result.content[0].text).toContain("MSG-ERR");
+  });
+
+  it("should include tool definition with correct schema", () => {
+    expect(tool.name).toBe("send_message");
+    expect(tool.description).toContain("Send a message");
+    expect(tool.inputSchema.type).toBe("object");
+    expect(tool.inputSchema.properties).toHaveProperty("chat_id");
+    expect(tool.inputSchema.properties).toHaveProperty("message");
+    expect(tool.inputSchema.required).toContain("chat_id");
+    expect(tool.inputSchema.required).toContain("message");
+  });
+});
diff --git a/src/lib/mcp/telegram/tools/__tests__/toolDefinitions.test.ts b/src/lib/mcp/telegram/tools/__tests__/toolDefinitions.test.ts
new file mode 100644
index 000000000..a1780c73e
--- /dev/null
+++ b/src/lib/mcp/telegram/tools/__tests__/toolDefinitions.test.ts
@@ -0,0 +1,147 @@
+import { describe, it, expect } from "vitest";
+import * as tools from "../index";
+import { TELEGRAM_MCP_TOOL_NAMES } from "../../types";
+import type { MCPTool } from "../../../types";
+
+describe("Tool Definitions", () => {
+  // Extract tool definitions (exports ending with "Tool")
+  const getToolDefinitions = (): Array<{ key: string; tool: MCPTool }> => {
+    return Object.entries(tools)
+      .filter(([key]) => key.endsWith("Tool"))
+      .map(([key, tool]) => ({ key, tool: tool as MCPTool }));
+  };
+
+  // Extract handler functions (exports not ending with "Tool")
+  const getHandlers = (): Array<{ key: string; handler: Function }> => {
+    return Object.entries(tools)
+      .filter(([key]) => !key.endsWith("Tool"))
+      .filter(([, value]) => typeof value === "function")
+      .map(([key, handler]) => ({ key, handler: handler as Function }));
+  };
+
+  it("should export tool definitions with name, description, and inputSchema", () => {
+    const toolDefs = getToolDefinitions();
+
+    expect(toolDefs.length).toBeGreaterThan(0);
+
+    toolDefs.forEach(({ tool }) => {
+      expect(tool).toBeDefined();
+      expect(tool.name).toBeDefined();
+      expect(typeof tool.name).toBe("string");
+      expect(tool.name.length).toBeGreaterThan(0);
+
+      expect(tool.description).toBeDefined();
+      expect(typeof tool.description).toBe("string");
+      expect(tool.description.length).toBeGreaterThan(0);
+
+      expect(tool.inputSchema).toBeDefined();
+      expect(tool.inputSchema.type).toBe("object");
+    });
+  });
+
+  it("should export handler functions", () => {
+    const handlers = getHandlers();
+
+    expect(handlers.length).toBeGreaterThan(0);
+
+    handlers.forEach(({ handler }) => {
+      expect(handler).toBeDefined();
+      expect(typeof handler).toBe("function");
+    });
+  });
+
+  it("should have inputSchema with properties object", () => {
+    const toolDefs = getToolDefinitions();
+
+    toolDefs.forEach(({ tool }) => {
+      expect(tool.inputSchema.properties).toBeDefined();
+      expect(typeof tool.inputSchema.properties).toBe("object");
+    });
+  });
+
+  it("should have all TELEGRAM_MCP_TOOL_NAMES with corresponding tool exports", () => {
+    const exportedToolNames = getToolDefinitions().map(({ tool }) => tool.name);
+
+    TELEGRAM_MCP_TOOL_NAMES.forEach((toolName) => {
+      expect(
+        exportedToolNames,
+        `Tool "${toolName}" from TELEGRAM_MCP_TOOL_NAMES should be exported`
+      ).toContain(toolName);
+    });
+  });
+
+  it("should have unique tool names", () => {
+    const toolNames = getToolDefinitions().map(({ tool }) => tool.name);
+    const uniqueNames = new Set(toolNames);
+    expect(uniqueNames.size).toBe(toolNames.length);
+  });
+
+  it("should have at least 79 tool definitions", () => {
+    const toolCount = getToolDefinitions().length;
+    expect(toolCount).toBeGreaterThanOrEqual(79);
+  });
+
+  it("should have required fields in inputSchema where appropriate", () => {
+    const toolDefs = getToolDefinitions();
+
+    toolDefs.forEach(({ tool }) => {
+      if (tool.inputSchema.required) {
+        expect(Array.isArray(tool.inputSchema.required)).toBe(true);
+
+        tool.inputSchema.required.forEach((requiredField: string) => {
+          expect(tool.inputSchema.properties).toHaveProperty(requiredField);
+        });
+      }
+    });
+  });
+
+  it("should have valid property types in inputSchema", () => {
+    const validTypes = ["string", "number", "integer", "boolean", "array", "object"];
+    const toolDefs = getToolDefinitions();
+
+    toolDefs.forEach(({ tool }) => {
+      Object.values(tool.inputSchema.properties).forEach((prop: any) => {
+        if (prop.type) {
+          expect(validTypes).toContain(prop.type);
+        }
+      });
+    });
+  });
+
+  it("should have descriptions for all properties", () => {
+    const toolDefs = getToolDefinitions();
+
+    toolDefs.forEach(({ tool }) => {
+      Object.entries(tool.inputSchema.properties).forEach(([propName, prop]: [string, any]) => {
+        expect(
+          prop.description,
+          `Property "${propName}" in tool "${tool.name}" should have a description`
+        ).toBeDefined();
+        expect(typeof prop.description).toBe("string");
+        expect(prop.description.length).toBeGreaterThan(0);
+      });
+    });
+  });
+
+  it("should match exported tool count with TELEGRAM_MCP_TOOL_NAMES count", () => {
+    const exportedToolCount = getToolDefinitions().length;
+    expect(exportedToolCount).toBe(TELEGRAM_MCP_TOOL_NAMES.length);
+  });
+
+  it("should have matching handler for each tool definition", () => {
+    const toolDefs = getToolDefinitions();
+    const handlers = getHandlers();
+
+    expect(toolDefs.length).toBe(handlers.length);
+
+    toolDefs.forEach(({ key: toolKey }) => {
+      // Tool export key ends with "Tool", handler key should be the base name
+      const baseName = toolKey.replace(/Tool$/, "");
+      const hasMatchingHandler = handlers.some(({ key }) => key === baseName);
+      expect(
+        hasMatchingHandler,
+        `Tool "${toolKey}" should have a matching handler "${baseName}"`
+      ).toBe(true);
+    });
+  });
+});
diff --git a/src/lib/mcp/telegram/tools/addContact.ts b/src/lib/mcp/telegram/tools/addContact.ts
index 458defd36..4960a173d 100644
--- a/src/lib/mcp/telegram/tools/addContact.ts
+++ b/src/lib/mcp/telegram/tools/addContact.ts
@@ -1,10 +1,8 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import bigInt from "big-integer";
 import { optString } from "../args";
+import { addContact as addContactApi } from "../api/addContact";
 
 export const tool: MCPTool = {
   name: "add_contact",
@@ -28,42 +26,15 @@ export async function addContact(
     const phone = typeof args.phone === "string" ? args.phone : "";
     const firstName =
       typeof args.first_name === "string" ? args.first_name : "";
-    const lastName = optString(args, "last_name") ?? "";
+    const lastName = optString(args, "last_name");
 
-    if (!phone)
-      return {
-        content: [{ type: "text", text: "phone is required" }],
-        isError: true,
-      };
-    if (!firstName)
-      return {
-        content: [{ type: "text", text: "first_name is required" }],
-        isError: true,
-      };
-
-    const client = mtprotoService.getClient();
-
-    await mtprotoService.withFloodWaitHandling(async () => {
-      await client.invoke(
-        new Api.contacts.ImportContacts({
-          contacts: [
-            new Api.InputPhoneContact({
-              clientId: bigInt(0),
-              phone,
-              firstName,
-              lastName,
-            }),
-          ],
-        }),
-      );
-    });
+    await addContactApi(phone, firstName, lastName);
 
     return {
       content: [
         {
           type: "text",
-          text:
-            "Contact " + firstName + " " + lastName + " (" + phone + ") added.",
+          text: `Contact ${firstName} ${lastName ?? ""} (${phone}) added.`,
         },
       ],
     };
diff --git a/src/lib/mcp/telegram/tools/archiveChat.ts b/src/lib/mcp/telegram/tools/archiveChat.ts
index 370a6d375..b09830d3f 100644
--- a/src/lib/mcp/telegram/tools/archiveChat.ts
+++ b/src/lib/mcp/telegram/tools/archiveChat.ts
@@ -2,9 +2,7 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { validateId } from "../../validation";
-import { getChatById } from "../telegramApi";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
+import { archiveChat as archiveChatApi } from "../api/archiveChat";
 
 export const tool: MCPTool = {
   name: "archive_chat",
@@ -24,32 +22,11 @@ export async function archiveChat(
 ): Promise<MCPToolResult> {
   try {
     const chatId = validateId(args.chat_id, "chat_id");
-
-    const chat = getChatById(chatId);
-    if (!chat)
-      return {
-        content: [{ type: "text", text: `Chat not found: ${chatId}` }],
-        isError: true,
-      };
-
-    const client = mtprotoService.getClient();
-    const entity = chat.username ? chat.username : chat.id;
-
-    await mtprotoService.withFloodWaitHandling(async () => {
-      const inputPeer = await client.getInputEntity(entity);
-      await client.invoke(
-        new Api.folders.EditPeerFolders({
-          folderPeers: [
-            new Api.InputFolderPeer({
-              peer: inputPeer,
-              folderId: 1, // 1 = Archive folder
-            }),
-          ],
-        }),
-      );
-    });
-
-    return { content: [{ type: "text", text: `Chat ${chatId} archived.` }] };
+    const { fromCache } = await archiveChatApi(chatId);
+    return {
+      content: [{ type: "text", text: `Chat ${chatId} archived.` }],
+      fromCache,
+    };
   } catch (error) {
     return logAndFormatError(
       "archive_chat",
diff --git a/src/lib/mcp/telegram/tools/banUser.ts b/src/lib/mcp/telegram/tools/banUser.ts
index e93abeda3..35888b9b4 100644
--- a/src/lib/mcp/telegram/tools/banUser.ts
+++ b/src/lib/mcp/telegram/tools/banUser.ts
@@ -2,10 +2,8 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { validateId } from "../../validation";
-import { getChatById } from "../telegramApi";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import { toInputChannel, toInputPeer } from "../apiCastHelpers";
+import { banUser as banUserApi } from "../api/banUser";
+import { getChatById } from "../api/helpers";
 
 export const tool: MCPTool = {
   name: "ban_user",
@@ -28,55 +26,14 @@ export async function banUser(
     const chatId = validateId(args.chat_id, "chat_id");
     const userId = validateId(args.user_id, "user_id");
 
+    await banUserApi(chatId, userId);
+
     const chat = getChatById(chatId);
-    if (!chat)
-      return {
-        content: [{ type: "text", text: `Chat not found: ${chatId}` }],
-        isError: true,
-      };
-
-    if (chat.type !== "channel" && chat.type !== "supergroup") {
-      return {
-        content: [
-          {
-            type: "text",
-            text: "Ban is only available for channels/supergroups.",
-          },
-        ],
-        isError: true,
-      };
-    }
-
-    const client = mtprotoService.getClient();
-    const entity = chat.username ? chat.username : chat.id;
-
-    await mtprotoService.withFloodWaitHandling(async () => {
-      const inputChannel = await client.getInputEntity(entity);
-      const inputUser = await client.getInputEntity(userId);
-      await client.invoke(
-        new Api.channels.EditBanned({
-          channel: toInputChannel(inputChannel),
-          participant: toInputPeer(inputUser),
-          bannedRights: new Api.ChatBannedRights({
-            viewMessages: true,
-            sendMessages: true,
-            sendMedia: true,
-            sendStickers: true,
-            sendGifs: true,
-            sendGames: true,
-            sendInline: true,
-            embedLinks: true,
-            untilDate: 0,
-          }),
-        }),
-      );
-    });
-
     return {
       content: [
         {
           type: "text",
-          text: `User ${userId} banned from ${chat.title ?? chatId}.`,
+          text: `User ${userId} banned from ${chat?.title ?? chatId}.`,
         },
       ],
     };
diff --git a/src/lib/mcp/telegram/tools/blockUser.ts b/src/lib/mcp/telegram/tools/blockUser.ts
index b0870b3a9..d7af31044 100644
--- a/src/lib/mcp/telegram/tools/blockUser.ts
+++ b/src/lib/mcp/telegram/tools/blockUser.ts
@@ -2,9 +2,7 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { validateId } from "../../validation";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import { toInputPeer } from "../apiCastHelpers";
+import { blockUser as blockUserApi } from "../api/blockUser";
 
 export const tool: MCPTool = {
   name: "block_user",
@@ -24,17 +22,11 @@ export async function blockUser(
 ): Promise<MCPToolResult> {
   try {
     const userId = validateId(args.user_id, "user_id");
-    const client = mtprotoService.getClient();
 
-    await mtprotoService.withFloodWaitHandling(async () => {
-      const inputUser = await client.getInputEntity(userId);
-      await client.invoke(
-        new Api.contacts.Block({ id: toInputPeer(inputUser) }),
-      );
-    });
+    await blockUserApi(userId);
 
     return {
-      content: [{ type: "text", text: "User " + userId + " blocked." }],
+      content: [{ type: "text", text: `User ${userId} blocked.` }],
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/clearDraft.ts b/src/lib/mcp/telegram/tools/clearDraft.ts
index f973f49dd..baa8b3f79 100644
--- a/src/lib/mcp/telegram/tools/clearDraft.ts
+++ b/src/lib/mcp/telegram/tools/clearDraft.ts
@@ -2,9 +2,7 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { validateId } from "../../validation";
-import { getChatById } from "../telegramApi";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
+import { clearDraft as clearDraftApi } from "../api/clearDraft";
 
 export const tool: MCPTool = {
   name: "clear_draft",
@@ -25,30 +23,13 @@ export async function clearDraft(
   try {
     const chatId = validateId(args.chat_id, "chat_id");
 
-    const chat = getChatById(chatId);
-    if (!chat)
-      return {
-        content: [{ type: "text", text: "Chat not found: " + chatId }],
-        isError: true,
-      };
-
-    const client = mtprotoService.getClient();
-    const entity = chat.username ? chat.username : chat.id;
-
-    await mtprotoService.withFloodWaitHandling(async () => {
-      const inputPeer = await client.getInputEntity(entity);
-      await client.invoke(
-        new Api.messages.SaveDraft({
-          peer: inputPeer,
-          message: "",
-        }),
-      );
-    });
+    const { fromCache } = await clearDraftApi(chatId);
 
     return {
       content: [
         { type: "text", text: "Draft cleared in chat " + chatId + "." },
       ],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/createChannel.ts b/src/lib/mcp/telegram/tools/createChannel.ts
index 35382892b..c42bc71c5 100644
--- a/src/lib/mcp/telegram/tools/createChannel.ts
+++ b/src/lib/mcp/telegram/tools/createChannel.ts
@@ -1,11 +1,8 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
 import { optString } from "../args";
-import type { ResultWithChats } from "../apiResultTypes";
-import { narrow } from "../apiCastHelpers";
+import { createChannel as createChannelApi } from "../api/createChannel";
 
 export const tool: MCPTool = {
   name: "create_channel",
@@ -39,26 +36,16 @@ export async function createChannel(
 
     const about = optString(args, "about") ?? "";
     const megagroup = args.megagroup === true;
-    const client = mtprotoService.getClient();
 
-    const result = await mtprotoService.withFloodWaitHandling(async () => {
-      return client.invoke(
-        new Api.channels.CreateChannel({
-          title,
-          about,
-          megagroup,
-          broadcast: !megagroup,
-        }),
-      );
-    });
-
-    const channelId =
-      narrow<ResultWithChats>(result)?.chats?.[0]?.id ?? "unknown";
-    const type = megagroup ? "Supergroup" : "Channel";
+    const { data, fromCache } = await createChannelApi(title, about, megagroup);
     return {
       content: [
-        { type: "text", text: `${type} "${title}" created. ID: ${channelId}` },
+        {
+          type: "text",
+          text: `${data.type} "${title}" created. ID: ${data.id}`,
+        },
       ],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/createGroup.ts b/src/lib/mcp/telegram/tools/createGroup.ts
index 9a42e1e35..93bd25459 100644
--- a/src/lib/mcp/telegram/tools/createGroup.ts
+++ b/src/lib/mcp/telegram/tools/createGroup.ts
@@ -1,10 +1,7 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import type { ResultWithChats } from "../apiResultTypes";
-import { toInputUser, narrow } from "../apiCastHelpers";
+import { createGroup as createGroupApi } from "../api/createGroup";
 
 export const tool: MCPTool = {
   name: "create_group",
@@ -42,23 +39,15 @@ export async function createGroup(
         isError: true,
       };
 
-    const client = mtprotoService.getClient();
-
-    const users: Api.TypeInputUser[] = [];
-    for (const uid of userIds) {
-      const inputUser = await client.getInputEntity(String(uid));
-      users.push(toInputUser(inputUser));
-    }
-
-    const result = await mtprotoService.withFloodWaitHandling(async () => {
-      return client.invoke(new Api.messages.CreateChat({ title, users }));
-    });
-
-    const chatId = narrow<ResultWithChats>(result)?.chats?.[0]?.id ?? "unknown";
+    const { data, fromCache } = await createGroupApi(
+      title,
+      userIds.map(String),
+    );
     return {
       content: [
-        { type: "text", text: `Group "${title}" created. Chat ID: ${chatId}` },
+        { type: "text", text: `Group "${title}" created. Chat ID: ${data.id}` },
       ],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/createPoll.ts b/src/lib/mcp/telegram/tools/createPoll.ts
index 9a95596cc..43fa1bcd4 100644
--- a/src/lib/mcp/telegram/tools/createPoll.ts
+++ b/src/lib/mcp/telegram/tools/createPoll.ts
@@ -2,10 +2,7 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { validateId } from "../../validation";
-import { getChatById } from "../telegramApi";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import bigInt from "big-integer";
+import { createPoll as createPollApi } from "../api/createPoll";
 
 export const tool: MCPTool = {
   name: "create_poll",
@@ -41,44 +38,12 @@ export async function createPoll(
         isError: true,
       };
 
-    const chat = getChatById(chatId);
-    if (!chat)
-      return {
-        content: [{ type: "text", text: "Chat not found: " + chatId }],
-        isError: true,
-      };
+    const { fromCache } = await createPollApi(chatId, question, options);
 
-    const client = mtprotoService.getClient();
-    const entity = chat.username ? chat.username : chat.id;
-
-    await mtprotoService.withFloodWaitHandling(async () => {
-      const inputPeer = await client.getInputEntity(entity);
-      await client.invoke(
-        new Api.messages.SendMedia({
-          peer: inputPeer,
-          media: new Api.InputMediaPoll({
-            poll: new Api.Poll({
-              id: bigInt(0),
-              question: new Api.TextWithEntities({
-                text: question,
-                entities: [],
-              }),
-              answers: options.map(
-                (opt, i) =>
-                  new Api.PollAnswer({
-                    text: new Api.TextWithEntities({ text: opt, entities: [] }),
-                    option: Buffer.from([i]),
-                  }),
-              ),
-            }),
-          }),
-          message: "",
-          randomId: bigInt(Math.floor(Math.random() * Number.MAX_SAFE_INTEGER)),
-        }),
-      );
-    });
-
-    return { content: [{ type: "text", text: "Poll created: " + question }] };
+    return {
+      content: [{ type: "text", text: "Poll created: " + question }],
+      fromCache,
+    };
   } catch (error) {
     return logAndFormatError(
       "create_poll",
diff --git a/src/lib/mcp/telegram/tools/deleteChatPhoto.ts b/src/lib/mcp/telegram/tools/deleteChatPhoto.ts
index 592d140b7..bd2e4dbb6 100644
--- a/src/lib/mcp/telegram/tools/deleteChatPhoto.ts
+++ b/src/lib/mcp/telegram/tools/deleteChatPhoto.ts
@@ -2,11 +2,7 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { validateId } from "../../validation";
-import { getChatById } from "../telegramApi";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import bigInt from "big-integer";
-import { toInputChannel } from "../apiCastHelpers";
+import { deleteChatPhoto as deleteChatPhotoApi } from "../api/deleteChatPhoto";
 
 export const tool: MCPTool = {
   name: "delete_chat_photo",
@@ -26,40 +22,10 @@ export async function deleteChatPhoto(
 ): Promise<MCPToolResult> {
   try {
     const chatId = validateId(args.chat_id, "chat_id");
-
-    const chat = getChatById(chatId);
-    if (!chat)
-      return {
-        content: [{ type: "text", text: `Chat not found: ${chatId}` }],
-        isError: true,
-      };
-
-    const client = mtprotoService.getClient();
-    const entity = chat.username ? chat.username : chat.id;
-
-    if (chat.type === "channel" || chat.type === "supergroup") {
-      await mtprotoService.withFloodWaitHandling(async () => {
-        const inputChannel = await client.getInputEntity(entity);
-        await client.invoke(
-          new Api.channels.EditPhoto({
-            channel: toInputChannel(inputChannel),
-            photo: new Api.InputChatPhotoEmpty(),
-          }),
-        );
-      });
-    } else {
-      await mtprotoService.withFloodWaitHandling(async () => {
-        await client.invoke(
-          new Api.messages.EditChatPhoto({
-            chatId: bigInt(chat.id),
-            photo: new Api.InputChatPhotoEmpty(),
-          }),
-        );
-      });
-    }
-
+    const { fromCache } = await deleteChatPhotoApi(chatId);
     return {
       content: [{ type: "text", text: `Chat photo deleted for ${chatId}.` }],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/deleteContact.ts b/src/lib/mcp/telegram/tools/deleteContact.ts
index 48eb92bba..ab6130502 100644
--- a/src/lib/mcp/telegram/tools/deleteContact.ts
+++ b/src/lib/mcp/telegram/tools/deleteContact.ts
@@ -2,9 +2,7 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { validateId } from "../../validation";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import { toInputUser } from "../apiCastHelpers";
+import { deleteContact as deleteContactApi } from "../api/deleteContact";
 
 export const tool: MCPTool = {
   name: "delete_contact",
@@ -27,19 +25,11 @@ export async function deleteContact(
 ): Promise<MCPToolResult> {
   try {
     const userId = validateId(args.user_id, "user_id");
-    const client = mtprotoService.getClient();
 
-    await mtprotoService.withFloodWaitHandling(async () => {
-      const inputUser = await client.getInputEntity(userId);
-      await client.invoke(
-        new Api.contacts.DeleteContacts({
-          id: [toInputUser(inputUser)],
-        }),
-      );
-    });
+    await deleteContactApi(userId);
 
     return {
-      content: [{ type: "text", text: "Contact " + userId + " deleted." }],
+      content: [{ type: "text", text: `Contact ${userId} deleted.` }],
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/deleteMessage.ts b/src/lib/mcp/telegram/tools/deleteMessage.ts
index 073fc9695..2835220c1 100644
--- a/src/lib/mcp/telegram/tools/deleteMessage.ts
+++ b/src/lib/mcp/telegram/tools/deleteMessage.ts
@@ -1,9 +1,8 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { getChatById } from "../telegramApi";
-import { validateId } from "../../validation";
-import { mtprotoService } from "../../../../services/mtprotoService";
+import { validateId, validatePositiveInt } from "../../validation";
+import { deleteMessage as deleteMessageApi } from "../api/deleteMessage";
 
 export const tool: MCPTool = {
   name: "delete_message",
@@ -24,39 +23,15 @@ export async function deleteMessage(
 ): Promise<MCPToolResult> {
   try {
     const chatId = validateId(args.chat_id, "chat_id");
-    const messageId =
-      typeof args.message_id === "number" && Number.isInteger(args.message_id)
-        ? args.message_id
-        : undefined;
+    const messageId = validatePositiveInt(args.message_id, "message_id");
 
-    if (messageId === undefined) {
-      return {
-        content: [
-          { type: "text", text: "message_id must be a positive integer" },
-        ],
-        isError: true,
-      };
-    }
-
-    const chat = getChatById(chatId);
-    if (!chat) {
-      return {
-        content: [{ type: "text", text: `Chat not found: ${chatId}` }],
-        isError: true,
-      };
-    }
-
-    const entity = chat.username ? chat.username : chat.id;
-    const client = mtprotoService.getClient();
-
-    await mtprotoService.withFloodWaitHandling(async () => {
-      await client.deleteMessages(entity, [messageId], { revoke: true });
-    });
+    const { fromCache } = await deleteMessageApi(chatId, messageId);
 
     return {
       content: [
         { type: "text", text: `Message ${messageId} deleted successfully.` },
       ],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/deleteProfilePhoto.ts b/src/lib/mcp/telegram/tools/deleteProfilePhoto.ts
index 1f9f5e684..d53422ea0 100644
--- a/src/lib/mcp/telegram/tools/deleteProfilePhoto.ts
+++ b/src/lib/mcp/telegram/tools/deleteProfilePhoto.ts
@@ -1,11 +1,7 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import bigInt from "big-integer";
-import type { ApiPhoto } from "../apiResultTypes";
-import { narrow } from "../apiCastHelpers";
+import { deleteProfilePhoto as deleteProfilePhotoApi } from "../api/deleteProfilePhoto";
 
 export const tool: MCPTool = {
   name: "delete_profile_photo",
@@ -18,47 +14,12 @@ export async function deleteProfilePhoto(
   _context: TelegramMCPContext,
 ): Promise<MCPToolResult> {
   try {
-    const client = mtprotoService.getClient();
+    const { fromCache } = await deleteProfilePhotoApi();
 
-    const photos = await mtprotoService.withFloodWaitHandling(async () => {
-      return client.invoke(
-        new Api.photos.GetUserPhotos({
-          userId: new Api.InputUserSelf(),
-          offset: 0,
-          maxId: bigInt(0),
-          limit: 1,
-        }),
-      );
-    });
-
-    if (
-      !photos ||
-      !("photos" in photos) ||
-      !Array.isArray(photos.photos) ||
-      photos.photos.length === 0
-    ) {
-      return {
-        content: [{ type: "text", text: "No profile photo to delete." }],
-      };
-    }
-
-    const photo = narrow<ApiPhoto>(photos.photos[0]);
-
-    await mtprotoService.withFloodWaitHandling(async () => {
-      await client.invoke(
-        new Api.photos.DeletePhotos({
-          id: [
-            new Api.InputPhoto({
-              id: photo.id,
-              accessHash: photo.accessHash,
-              fileReference: photo.fileReference,
-            }),
-          ],
-        }),
-      );
-    });
-
-    return { content: [{ type: "text", text: "Profile photo deleted." }] };
+    return {
+      content: [{ type: "text", text: "Profile photo deleted." }],
+      fromCache,
+    };
   } catch (error) {
     return logAndFormatError(
       "delete_profile_photo",
diff --git a/src/lib/mcp/telegram/tools/demoteAdmin.ts b/src/lib/mcp/telegram/tools/demoteAdmin.ts
index c717985b7..74571a439 100644
--- a/src/lib/mcp/telegram/tools/demoteAdmin.ts
+++ b/src/lib/mcp/telegram/tools/demoteAdmin.ts
@@ -2,10 +2,8 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { validateId } from "../../validation";
-import { getChatById } from "../telegramApi";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import { toInputChannel, toInputUser } from "../apiCastHelpers";
+import { demoteAdmin as demoteAdminApi } from "../api/demoteAdmin";
+import { getChatById } from "../api/helpers";
 
 export const tool: MCPTool = {
   name: "demote_admin",
@@ -28,46 +26,14 @@ export async function demoteAdmin(
     const chatId = validateId(args.chat_id, "chat_id");
     const userId = validateId(args.user_id, "user_id");
 
+    await demoteAdminApi(chatId, userId);
+
     const chat = getChatById(chatId);
-    if (!chat)
-      return {
-        content: [{ type: "text", text: `Chat not found: ${chatId}` }],
-        isError: true,
-      };
-
-    if (chat.type !== "channel" && chat.type !== "supergroup") {
-      return {
-        content: [
-          {
-            type: "text",
-            text: "Admin demotion is only available for channels/supergroups.",
-          },
-        ],
-        isError: true,
-      };
-    }
-
-    const client = mtprotoService.getClient();
-    const entity = chat.username ? chat.username : chat.id;
-
-    await mtprotoService.withFloodWaitHandling(async () => {
-      const inputChannel = await client.getInputEntity(entity);
-      const inputUser = await client.getInputEntity(userId);
-      await client.invoke(
-        new Api.channels.EditAdmin({
-          channel: toInputChannel(inputChannel),
-          userId: toInputUser(inputUser),
-          adminRights: new Api.ChatAdminRights({}),
-          rank: "",
-        }),
-      );
-    });
-
     return {
       content: [
         {
           type: "text",
-          text: `User ${userId} demoted in ${chat.title ?? chatId}.`,
+          text: `User ${userId} demoted in ${chat?.title ?? chatId}.`,
         },
       ],
     };
diff --git a/src/lib/mcp/telegram/tools/editChatPhoto.ts b/src/lib/mcp/telegram/tools/editChatPhoto.ts
index 241f26082..f24aaeeb8 100644
--- a/src/lib/mcp/telegram/tools/editChatPhoto.ts
+++ b/src/lib/mcp/telegram/tools/editChatPhoto.ts
@@ -1,5 +1,8 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
+import { ErrorCategory, logAndFormatError } from "../../errorHandler";
+import { validateId } from "../../validation";
+import { editChatPhoto as editChatPhotoApi } from "../api/editChatPhoto";
 
 export const tool: MCPTool = {
   name: "edit_chat_photo",
@@ -15,16 +18,22 @@ export const tool: MCPTool = {
 };
 
 export async function editChatPhoto(
-  _args: Record<string, unknown>,
+  args: Record<string, unknown>,
   _context: TelegramMCPContext,
 ): Promise<MCPToolResult> {
-  return {
-    content: [
-      {
-        type: "text",
-        text: "edit_chat_photo requires file upload which is not supported via MCP text interface. Use the Telegram client directly.",
-      },
-    ],
-    isError: true,
-  };
+  try {
+    const chatId = validateId(args.chat_id, "chat_id");
+    const filePath = typeof args.file_path === "string" ? args.file_path : "";
+    await editChatPhotoApi(chatId, filePath);
+    return {
+      content: [{ type: "text", text: "Unreachable code" }],
+      isError: true,
+    };
+  } catch (error) {
+    return logAndFormatError(
+      "edit_chat_photo",
+      error instanceof Error ? error : new Error(String(error)),
+      ErrorCategory.GROUP,
+    );
+  }
 }
diff --git a/src/lib/mcp/telegram/tools/editChatTitle.ts b/src/lib/mcp/telegram/tools/editChatTitle.ts
index d858bca8f..be100a941 100644
--- a/src/lib/mcp/telegram/tools/editChatTitle.ts
+++ b/src/lib/mcp/telegram/tools/editChatTitle.ts
@@ -2,11 +2,7 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { validateId } from "../../validation";
-import { getChatById } from "../telegramApi";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import bigInt from "big-integer";
-import { toInputChannel } from "../apiCastHelpers";
+import { editChatTitle as editChatTitleApi } from "../api/editChatTitle";
 
 export const tool: MCPTool = {
   name: "edit_chat_title",
@@ -34,39 +30,10 @@ export async function editChatTitle(
         isError: true,
       };
 
-    const chat = getChatById(chatId);
-    if (!chat)
-      return {
-        content: [{ type: "text", text: `Chat not found: ${chatId}` }],
-        isError: true,
-      };
-
-    const client = mtprotoService.getClient();
-    const entity = chat.username ? chat.username : chat.id;
-
-    if (chat.type === "channel" || chat.type === "supergroup") {
-      await mtprotoService.withFloodWaitHandling(async () => {
-        const inputChannel = await client.getInputEntity(entity);
-        await client.invoke(
-          new Api.channels.EditTitle({
-            channel: toInputChannel(inputChannel),
-            title,
-          }),
-        );
-      });
-    } else {
-      await mtprotoService.withFloodWaitHandling(async () => {
-        await client.invoke(
-          new Api.messages.EditChatTitle({
-            chatId: bigInt(chat.id),
-            title,
-          }),
-        );
-      });
-    }
-
+    const { fromCache } = await editChatTitleApi(chatId, title);
     return {
       content: [{ type: "text", text: `Chat title updated to "${title}".` }],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/editMessage.ts b/src/lib/mcp/telegram/tools/editMessage.ts
index d37096566..98940f3aa 100644
--- a/src/lib/mcp/telegram/tools/editMessage.ts
+++ b/src/lib/mcp/telegram/tools/editMessage.ts
@@ -1,9 +1,8 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { getChatById } from "../telegramApi";
-import { validateId } from "../../validation";
-import { mtprotoService } from "../../../../services/mtprotoService";
+import { validateId, validatePositiveInt } from "../../validation";
+import { editMessage as editMessageApi } from "../api/editMessage";
 
 export const tool: MCPTool = {
   name: "edit_message",
@@ -25,20 +24,9 @@ export async function editMessage(
 ): Promise<MCPToolResult> {
   try {
     const chatId = validateId(args.chat_id, "chat_id");
-    const messageId =
-      typeof args.message_id === "number" && Number.isInteger(args.message_id)
-        ? args.message_id
-        : undefined;
+    const messageId = validatePositiveInt(args.message_id, "message_id");
     const newText = typeof args.new_text === "string" ? args.new_text : "";
 
-    if (messageId === undefined) {
-      return {
-        content: [
-          { type: "text", text: "message_id must be a positive integer" },
-        ],
-        isError: true,
-      };
-    }
     if (!newText) {
       return {
         content: [{ type: "text", text: "new_text is required" }],
@@ -46,25 +34,13 @@ export async function editMessage(
       };
     }
 
-    const chat = getChatById(chatId);
-    if (!chat) {
-      return {
-        content: [{ type: "text", text: `Chat not found: ${chatId}` }],
-        isError: true,
-      };
-    }
-
-    const entity = chat.username ? chat.username : chat.id;
-    const client = mtprotoService.getClient();
-
-    await mtprotoService.withFloodWaitHandling(async () => {
-      await client.editMessage(entity, { message: messageId, text: newText });
-    });
+    const { fromCache } = await editMessageApi(chatId, messageId, newText);
 
     return {
       content: [
         { type: "text", text: `Message ${messageId} edited successfully.` },
       ],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/exportChatInvite.ts b/src/lib/mcp/telegram/tools/exportChatInvite.ts
index 6164f862c..e387a9ab6 100644
--- a/src/lib/mcp/telegram/tools/exportChatInvite.ts
+++ b/src/lib/mcp/telegram/tools/exportChatInvite.ts
@@ -2,12 +2,8 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { validateId } from "../../validation";
-import { getChatById } from "../telegramApi";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
 import { optString } from "../args";
-import type { ChatInviteResult } from "../apiResultTypes";
-import { narrow } from "../apiCastHelpers";
+import { exportChatInvite as exportChatInviteApi } from "../api/exportChatInvite";
 
 export const tool: MCPTool = {
   name: "export_chat_invite",
@@ -36,38 +32,15 @@ export async function exportChatInvite(
     const usageLimit =
       typeof args.usage_limit === "number" ? args.usage_limit : undefined;
 
-    const chat = getChatById(chatId);
-    if (!chat)
-      return {
-        content: [{ type: "text", text: `Chat not found: ${chatId}` }],
-        isError: true,
-      };
-
-    const client = mtprotoService.getClient();
-    const entity = chat.username ? chat.username : chat.id;
-
-    const result = await mtprotoService.withFloodWaitHandling(async () => {
-      const inputPeer = await client.getInputEntity(entity);
-      return client.invoke(
-        new Api.messages.ExportChatInvite({
-          peer: inputPeer,
-          title: title ?? undefined,
-          expireDate: expireDate ?? undefined,
-          usageLimit: usageLimit ?? undefined,
-        }),
-      );
-    });
-
-    const link = narrow<ChatInviteResult>(result)?.link;
-    if (!link) {
-      return {
-        content: [{ type: "text", text: "Could not create invite link." }],
-        isError: true,
-      };
-    }
-
+    const { data, fromCache } = await exportChatInviteApi(
+      chatId,
+      title,
+      expireDate,
+      usageLimit,
+    );
     return {
-      content: [{ type: "text", text: `Invite link created: ${link}` }],
+      content: [{ type: "text", text: `Invite link created: ${data.link}` }],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/exportContacts.ts b/src/lib/mcp/telegram/tools/exportContacts.ts
index f124d2698..9dc3a9dc0 100644
--- a/src/lib/mcp/telegram/tools/exportContacts.ts
+++ b/src/lib/mcp/telegram/tools/exportContacts.ts
@@ -1,10 +1,7 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import bigInt from "big-integer";
-import type { ApiUser } from "../apiResultTypes";
+import { exportContacts as exportContactsApi } from "../api/exportContacts";
 
 export const tool: MCPTool = {
   name: "export_contacts",
@@ -17,31 +14,18 @@ export async function exportContacts(
   _context: TelegramMCPContext,
 ): Promise<MCPToolResult> {
   try {
-    const client = mtprotoService.getClient();
+    const { data: contacts, fromCache } = await exportContactsApi();
 
-    const result = await mtprotoService.withFloodWaitHandling(async () => {
-      return client.invoke(new Api.contacts.GetContacts({ hash: bigInt(0) }));
-    });
-
-    if (
-      !result ||
-      !("users" in result) ||
-      !Array.isArray(result.users) ||
-      result.users.length === 0
-    ) {
-      return { content: [{ type: "text", text: "No contacts to export." }] };
+    if (contacts.length === 0) {
+      return {
+        content: [{ type: "text", text: "No contacts to export." }],
+        fromCache,
+      };
     }
 
-    const contacts = result.users.map((u: ApiUser) => ({
-      id: String(u.id),
-      firstName: u.firstName ?? "",
-      lastName: u.lastName ?? "",
-      username: u.username ?? "",
-      phone: u.phone ?? "",
-    }));
-
     return {
       content: [{ type: "text", text: JSON.stringify(contacts, null, 2) }],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/forwardMessage.ts b/src/lib/mcp/telegram/tools/forwardMessage.ts
index 7c8e43f88..4636d9086 100644
--- a/src/lib/mcp/telegram/tools/forwardMessage.ts
+++ b/src/lib/mcp/telegram/tools/forwardMessage.ts
@@ -1,9 +1,8 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { getChatById } from "../telegramApi";
-import { validateId } from "../../validation";
-import { mtprotoService } from "../../../../services/mtprotoService";
+import { validateId, validatePositiveInt } from "../../validation";
+import { forwardMessage as forwardMessageApi } from "../api/forwardMessage";
 
 export const tool: MCPTool = {
   name: "forward_message",
@@ -26,48 +25,9 @@ export async function forwardMessage(
   try {
     const fromChatId = validateId(args.from_chat_id, "from_chat_id");
     const toChatId = validateId(args.to_chat_id, "to_chat_id");
-    const messageId =
-      typeof args.message_id === "number" && Number.isInteger(args.message_id)
-        ? args.message_id
-        : undefined;
+    const messageId = validatePositiveInt(args.message_id, "message_id");
 
-    if (messageId === undefined) {
-      return {
-        content: [
-          { type: "text", text: "message_id must be a positive integer" },
-        ],
-        isError: true,
-      };
-    }
-
-    const fromChat = getChatById(fromChatId);
-    if (!fromChat) {
-      return {
-        content: [
-          { type: "text", text: `Source chat not found: ${fromChatId}` },
-        ],
-        isError: true,
-      };
-    }
-
-    const toChat = getChatById(toChatId);
-    if (!toChat) {
-      return {
-        content: [{ type: "text", text: `Target chat not found: ${toChatId}` }],
-        isError: true,
-      };
-    }
-
-    const fromEntity = fromChat.username ? fromChat.username : fromChat.id;
-    const toEntity = toChat.username ? toChat.username : toChat.id;
-    const client = mtprotoService.getClient();
-
-    await mtprotoService.withFloodWaitHandling(async () => {
-      await client.forwardMessages(toEntity, {
-        messages: [messageId],
-        fromPeer: fromEntity,
-      });
-    });
+    const { fromCache } = await forwardMessageApi(fromChatId, toChatId, messageId);
 
     return {
       content: [
@@ -76,6 +36,7 @@ export async function forwardMessage(
           text: `Message ${messageId} forwarded from ${fromChatId} to ${toChatId}.`,
         },
       ],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/getAdmins.ts b/src/lib/mcp/telegram/tools/getAdmins.ts
index 0e1164489..91dba58d2 100644
--- a/src/lib/mcp/telegram/tools/getAdmins.ts
+++ b/src/lib/mcp/telegram/tools/getAdmins.ts
@@ -2,12 +2,7 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { validateId } from "../../validation";
-import { getChatById } from "../telegramApi";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import bigInt from "big-integer";
-import type { ApiUser } from "../apiResultTypes";
-import { toInputChannel, narrow } from "../apiCastHelpers";
+import { getAdmins as getAdminsApi } from "../api/getAdmins";
 
 export const tool: MCPTool = {
   name: "get_admins",
@@ -28,60 +23,25 @@ export async function getAdmins(
   try {
     const chatId = validateId(args.chat_id, "chat_id");
 
-    const chat = getChatById(chatId);
-    if (!chat)
-      return {
-        content: [{ type: "text", text: `Chat not found: ${chatId}` }],
-        isError: true,
-      };
-
-    const client = mtprotoService.getClient();
-    const entity = chat.username ? chat.username : chat.id;
-
-    let admins: ApiUser[] = [];
-
-    if (chat.type === "channel" || chat.type === "supergroup") {
-      const result = await mtprotoService.withFloodWaitHandling(async () => {
-        const inputChannel = await client.getInputEntity(entity);
-        return client.invoke(
-          new Api.channels.GetParticipants({
-            channel: toInputChannel(inputChannel),
-            filter: new Api.ChannelParticipantsAdmins(),
-            offset: 0,
-            limit: 100,
-            hash: bigInt(0),
-          }),
-        );
-      });
-      if (result && "users" in result && Array.isArray(result.users)) {
-        admins = narrow<ApiUser[]>(result.users);
-      }
-    } else {
-      const result = await mtprotoService.withFloodWaitHandling(async () => {
-        return client.invoke(
-          new Api.messages.GetFullChat({ chatId: bigInt(chat.id) }),
-        );
-      });
-      if (result && "users" in result && Array.isArray(result.users)) {
-        admins = narrow<ApiUser[]>(result.users);
-      }
-    }
+    const { data: admins, fromCache } = await getAdminsApi(chatId);
 
     if (admins.length === 0) {
-      return { content: [{ type: "text", text: "No admins found." }] };
+      return {
+        content: [{ type: "text", text: "No admins found." }],
+        fromCache,
+      };
     }
 
-    const lines = admins.map((u: ApiUser) => {
-      const name =
-        [u.firstName, u.lastName].filter(Boolean).join(" ") || "Unknown";
-      const username = u.username ? `@${u.username}` : "";
-      return `ID: ${u.id} | ${name} ${username}`.trim();
+    const lines = admins.map((a) => {
+      const username = a.username ? `@${a.username}` : "";
+      return `ID: ${a.id} | ${a.name} ${username}`.trim();
     });
 
     return {
       content: [
         { type: "text", text: `${lines.length} admins:\n${lines.join("\n")}` },
       ],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/getBannedUsers.ts b/src/lib/mcp/telegram/tools/getBannedUsers.ts
index 0240f56db..367f102fb 100644
--- a/src/lib/mcp/telegram/tools/getBannedUsers.ts
+++ b/src/lib/mcp/telegram/tools/getBannedUsers.ts
@@ -2,13 +2,8 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { validateId } from "../../validation";
-import { getChatById } from "../telegramApi";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
 import { optNumber } from "../args";
-import bigInt from "big-integer";
-import type { ApiUser } from "../apiResultTypes";
-import { toInputChannel } from "../apiCastHelpers";
+import { getBannedUsers as getBannedUsersApi } from "../api/getBannedUsers";
 
 export const tool: MCPTool = {
   name: "get_banned_users",
@@ -31,55 +26,21 @@ export async function getBannedUsers(
     const chatId = validateId(args.chat_id, "chat_id");
     const limit = optNumber(args, "limit", 50);
 
-    const chat = getChatById(chatId);
-    if (!chat)
-      return {
-        content: [{ type: "text", text: `Chat not found: ${chatId}` }],
-        isError: true,
-      };
+    const { data: bannedUsers, fromCache } = await getBannedUsersApi(
+      chatId,
+      limit,
+    );
 
-    if (chat.type !== "channel" && chat.type !== "supergroup") {
+    if (bannedUsers.length === 0) {
       return {
-        content: [
-          {
-            type: "text",
-            text: "Banned users list is only available for channels/supergroups.",
-          },
-        ],
-        isError: true,
+        content: [{ type: "text", text: "No banned users found." }],
+        fromCache,
       };
     }
 
-    const client = mtprotoService.getClient();
-    const entity = chat.username ? chat.username : chat.id;
-
-    const result = await mtprotoService.withFloodWaitHandling(async () => {
-      const inputChannel = await client.getInputEntity(entity);
-      return client.invoke(
-        new Api.channels.GetParticipants({
-          channel: toInputChannel(inputChannel),
-          filter: new Api.ChannelParticipantsKicked({ q: "" }),
-          offset: 0,
-          limit,
-          hash: bigInt(0),
-        }),
-      );
-    });
-
-    if (
-      !result ||
-      !("users" in result) ||
-      !Array.isArray(result.users) ||
-      result.users.length === 0
-    ) {
-      return { content: [{ type: "text", text: "No banned users found." }] };
-    }
-
-    const lines = result.users.map((u: ApiUser) => {
-      const name =
-        [u.firstName, u.lastName].filter(Boolean).join(" ") || "Unknown";
+    const lines = bannedUsers.map((u) => {
       const username = u.username ? `@${u.username}` : "";
-      return `ID: ${u.id} | ${name} ${username}`.trim();
+      return `ID: ${u.id} | ${u.name} ${username}`.trim();
     });
 
     return {
@@ -89,6 +50,7 @@ export async function getBannedUsers(
           text: `${lines.length} banned users:\n${lines.join("\n")}`,
         },
       ],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/getBlockedUsers.ts b/src/lib/mcp/telegram/tools/getBlockedUsers.ts
index 16ba3f9a4..1cc073614 100644
--- a/src/lib/mcp/telegram/tools/getBlockedUsers.ts
+++ b/src/lib/mcp/telegram/tools/getBlockedUsers.ts
@@ -1,10 +1,8 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
 import { optNumber } from "../args";
-import type { ApiUser } from "../apiResultTypes";
+import { getBlockedUsers as getBlockedUsersApi } from "../api/getBlockedUsers";
 
 export const tool: MCPTool = {
   name: "get_blocked_users",
@@ -23,29 +21,25 @@ export async function getBlockedUsers(
 ): Promise<MCPToolResult> {
   try {
     const limit = optNumber(args, "limit", 50);
-    const client = mtprotoService.getClient();
 
-    const result = await mtprotoService.withFloodWaitHandling(async () => {
-      return client.invoke(new Api.contacts.GetBlocked({ offset: 0, limit }));
-    });
+    const { data: blockedUsers, fromCache } = await getBlockedUsersApi(limit);
 
-    if (
-      !result ||
-      !("users" in result) ||
-      !Array.isArray(result.users) ||
-      result.users.length === 0
-    ) {
-      return { content: [{ type: "text", text: "No blocked users." }] };
+    if (blockedUsers.length === 0) {
+      return {
+        content: [{ type: "text", text: "No blocked users." }],
+        fromCache,
+      };
     }
 
-    const lines = result.users.map((u: ApiUser) => {
-      const name =
-        [u.firstName, u.lastName].filter(Boolean).join(" ") || "Unknown";
+    const lines = blockedUsers.map((u) => {
       const username = u.username ? `@${u.username}` : "";
-      return `ID: ${u.id} | ${name} ${username}`.trim();
+      return `ID: ${u.id} | ${u.name} ${username}`.trim();
     });
 
-    return { content: [{ type: "text", text: lines.join("\n") }] };
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      fromCache,
+    };
   } catch (error) {
     return logAndFormatError(
       "get_blocked_users",
diff --git a/src/lib/mcp/telegram/tools/getBotInfo.ts b/src/lib/mcp/telegram/tools/getBotInfo.ts
index 56f96b8e5..97eea2ad7 100644
--- a/src/lib/mcp/telegram/tools/getBotInfo.ts
+++ b/src/lib/mcp/telegram/tools/getBotInfo.ts
@@ -2,10 +2,7 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { validateId } from "../../validation";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import type { FullUserResult } from "../apiResultTypes";
-import { toInputUser, narrow } from "../apiCastHelpers";
+import { getBotInfo as getBotInfoApi } from "../api/getBotInfo";
 
 export const tool: MCPTool = {
   name: "get_bot_info",
@@ -25,44 +22,29 @@ export async function getBotInfo(
 ): Promise<MCPToolResult> {
   try {
     const botId = validateId(args.chat_id, "chat_id");
-    const client = mtprotoService.getClient();
 
-    const result = await mtprotoService.withFloodWaitHandling(async () => {
-      const inputUser = await client.getInputEntity(botId);
-      return client.invoke(
-        new Api.users.GetFullUser({ id: toInputUser(inputUser) }),
-      );
-    });
+    const { data: botInfo, fromCache } = await getBotInfoApi(botId);
 
-    const fullUser = narrow<FullUserResult>(result)?.fullUser;
-    const user = narrow<FullUserResult>(result)?.users?.[0];
-
-    if (!user) {
-      return {
-        content: [{ type: "text", text: "Bot not found: " + botId }],
-        isError: true,
-      };
-    }
-
-    const name =
-      [user.firstName, user.lastName].filter(Boolean).join(" ") || "Unknown";
     const lines = [
-      "Name: " + name,
-      "Username: @" + (user.username ?? "N/A"),
-      "ID: " + user.id,
-      "Bot: " + (user.bot ? "Yes" : "No"),
-      "About: " + (fullUser?.about ?? "N/A"),
-      "Bot Info Description: " + (fullUser?.botInfo?.description ?? "N/A"),
+      "Name: " + botInfo.name,
+      "Username: @" + botInfo.username,
+      "ID: " + botInfo.id,
+      "Bot: " + (botInfo.isBot ? "Yes" : "No"),
+      "About: " + (botInfo.about ?? "N/A"),
+      "Bot Info Description: " + (botInfo.botDescription ?? "N/A"),
     ];
 
-    if (fullUser?.botInfo?.commands) {
+    if (botInfo.commands && botInfo.commands.length > 0) {
       lines.push("Commands:");
-      for (const cmd of fullUser.botInfo.commands) {
+      for (const cmd of botInfo.commands) {
         lines.push("  /" + cmd.command + " - " + cmd.description);
       }
     }
 
-    return { content: [{ type: "text", text: lines.join("\n") }] };
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      fromCache,
+    };
   } catch (error) {
     return logAndFormatError(
       "get_bot_info",
diff --git a/src/lib/mcp/telegram/tools/getChat.ts b/src/lib/mcp/telegram/tools/getChat.ts
index 52bd2e736..3c8f80c99 100644
--- a/src/lib/mcp/telegram/tools/getChat.ts
+++ b/src/lib/mcp/telegram/tools/getChat.ts
@@ -8,10 +8,8 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { formatEntity, getChatById } from "../telegramApi";
 import { validateId } from "../../validation";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { enforceRateLimit } from "../../rateLimiter";
+import { getChat as getChatApi } from "../api/getChat";
 
 export const tool: MCPTool = {
   name: "get_chat",
@@ -34,67 +32,39 @@ export async function getChat(
 ): Promise<MCPToolResult> {
   try {
     const chatId = validateId(args.chat_id, "chat_id");
-    const chat = getChatById(chatId);
+    const { data: chatInfo, fromCache } = await getChatApi(chatId);
 
-    if (chat) {
-      // Cache hit — return cached data
-      return formatChatResult(chat);
-    }
-
-    // Cache miss — try Telegram API
-    try {
-      await enforceRateLimit("__api_fallback_chat");
-
-      const client = mtprotoService.getClient();
-      const entity = await mtprotoService.withFloodWaitHandling(async () => {
-        return client.getEntity(chatId);
-      });
-
-      if (!entity) {
-        return {
-          content: [{ type: "text", text: `Chat not found: ${chatId}` }],
-          isError: true,
-        };
-      }
-
-      const raw = entity as unknown as Record<string, unknown>;
-      const result: string[] = [];
-
-      result.push(`ID: ${raw.id ?? chatId}`);
-
-      // Determine type and title
-      const className = raw.className as string | undefined;
-      if (className === "User") {
-        const name =
-          [raw.firstName, raw.lastName].filter(Boolean).join(" ") || "Unknown";
-        result.push(`Name: ${name}`);
-        result.push(`Type: user`);
-        if (raw.username) result.push(`Username: @${raw.username}`);
-        if (raw.phone) result.push(`Phone: +${raw.phone}`);
-        if (raw.bot) result.push(`Bot: true`);
-      } else if (className === "Channel") {
-        result.push(`Title: ${raw.title ?? "Unknown"}`);
-        result.push(`Type: ${raw.megagroup ? "supergroup" : "channel"}`);
-        if (raw.username) result.push(`Username: @${raw.username}`);
-        if (raw.participantsCount)
-          result.push(`Participants: ${raw.participantsCount}`);
-      } else if (className === "Chat") {
-        result.push(`Title: ${raw.title ?? "Unknown"}`);
-        result.push(`Type: group`);
-        if (raw.participantsCount)
-          result.push(`Participants: ${raw.participantsCount}`);
-      } else {
-        result.push(`Title: ${raw.title ?? raw.firstName ?? "Unknown"}`);
-        result.push(`Type: unknown`);
-      }
-
-      return { content: [{ type: "text", text: result.join("\n") }] };
-    } catch {
+    if (!chatInfo) {
       return {
         content: [{ type: "text", text: `Chat not found: ${chatId}` }],
         isError: true,
       };
     }
+
+    const result: string[] = [];
+    result.push(`ID: ${chatInfo.id}`);
+    if (chatInfo.type === "user") {
+      result.push(`Name: ${chatInfo.name}`);
+    } else {
+      result.push(`Title: ${chatInfo.name}`);
+    }
+    result.push(`Type: ${chatInfo.type}`);
+    if (chatInfo.username) result.push(`Username: @${chatInfo.username}`);
+    if (chatInfo.phone) result.push(`Phone: +${chatInfo.phone}`);
+    if (chatInfo.isBot) result.push(`Bot: true`);
+    if (chatInfo.participantsCount)
+      result.push(`Participants: ${chatInfo.participantsCount}`);
+    if (chatInfo.unreadCount !== undefined)
+      result.push(`Unread Messages: ${chatInfo.unreadCount}`);
+    if (chatInfo.lastMessage) {
+      result.push(`Last Message: From ${chatInfo.lastMessage.from} at ${chatInfo.lastMessage.date}`);
+      result.push(`Message: ${chatInfo.lastMessage.text}`);
+    }
+
+    return {
+      content: [{ type: "text", text: result.join("\n") }],
+      fromCache,
+    };
   } catch (error) {
     return logAndFormatError(
       "get_chat",
@@ -103,31 +73,3 @@ export async function getChat(
     );
   }
 }
-
-function formatChatResult(
-  chat: ReturnType<typeof getChatById> & object,
-): MCPToolResult {
-  const entity = formatEntity(chat);
-  const result: string[] = [];
-
-  result.push(`ID: ${entity.id}`);
-  result.push(`Title: ${entity.name}`);
-  result.push(`Type: ${entity.type}`);
-  if (entity.username) result.push(`Username: @${entity.username}`);
-  if ("participantsCount" in chat && chat.participantsCount) {
-    result.push(`Participants: ${chat.participantsCount}`);
-  }
-  if ("unreadCount" in chat) {
-    result.push(`Unread Messages: ${chat.unreadCount ?? 0}`);
-  }
-
-  const lastMsg = (chat as { lastMessage?: { fromName?: string; fromId?: string; date: number; message?: string } }).lastMessage;
-  if (lastMsg) {
-    const from = lastMsg.fromName ?? lastMsg.fromId ?? "Unknown";
-    const date = new Date(lastMsg.date * 1000).toISOString();
-    result.push(`Last Message: From ${from} at ${date}`);
-    result.push(`Message: ${lastMsg.message || "[Media/No text]"}`);
-  }
-
-  return { content: [{ type: "text", text: result.join("\n") }] };
-}
diff --git a/src/lib/mcp/telegram/tools/getChats.ts b/src/lib/mcp/telegram/tools/getChats.ts
index c6dd5f0ae..18b1a2e98 100644
--- a/src/lib/mcp/telegram/tools/getChats.ts
+++ b/src/lib/mcp/telegram/tools/getChats.ts
@@ -7,7 +7,8 @@ import type { TelegramMCPContext } from "../types";
 
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { optNumber } from "../args";
-import { formatEntity, getChatsWithApiFallback } from "../telegramApi";
+import { getChats as getChatsApi } from "../api/getChats";
+import { formatEntity } from "../api/helpers";
 
 export const tool: MCPTool = {
   name: "get_chats",
@@ -38,11 +39,11 @@ export async function getChats(
     const pageSize = optNumber(args, "page_size", 20);
     const start = (page - 1) * pageSize;
 
-    const chats = await getChatsWithApiFallback(pageSize + start);
-    const paginatedChats = chats.slice(start, start + pageSize);
+    const { data: allChats, fromCache } = await getChatsApi(pageSize + start);
+    const paginatedChats = allChats.slice(start, start + pageSize);
 
     if (paginatedChats.length === 0) {
-      return { content: [{ type: "text", text: "Page out of range." }] };
+      return { content: [{ type: "text", text: "Page out of range." }], fromCache };
     }
 
     const lines = paginatedChats.map((chat) => {
@@ -50,7 +51,7 @@ export async function getChats(
       return `Chat ID: ${entity.id}, Title: ${entity.name}`;
     });
 
-    return { content: [{ type: "text", text: lines.join("\n") }] };
+    return { content: [{ type: "text", text: lines.join("\n") }], fromCache };
   } catch (error) {
     return logAndFormatError(
       "get_chats",
diff --git a/src/lib/mcp/telegram/tools/getContactChats.ts b/src/lib/mcp/telegram/tools/getContactChats.ts
index 82794c848..c7ecc1f31 100644
--- a/src/lib/mcp/telegram/tools/getContactChats.ts
+++ b/src/lib/mcp/telegram/tools/getContactChats.ts
@@ -1,8 +1,7 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { store } from "../../../../store";
-import { selectOrderedChats } from "../../../../store/telegramSelectors";
+import { getContactChats as getContactChatsApi } from "../api/getContactChats";
 
 export const tool: MCPTool = {
   name: "get_contact_chats",
@@ -15,27 +14,18 @@ export async function getContactChats(
   _context: TelegramMCPContext,
 ): Promise<MCPToolResult> {
   try {
-    const state = store.getState();
-    const chats = selectOrderedChats(state);
-    const dmChats = chats.filter((c) => c.type === "private");
+    const { data: dmChats, fromCache } = await getContactChatsApi();
 
     if (dmChats.length === 0) {
-      return { content: [{ type: "text", text: "No contact chats found." }] };
+      return { content: [{ type: "text", text: "No contact chats found." }], fromCache };
     }
 
     const lines = dmChats.map((c) => {
       const username = c.username ? "@" + c.username : "";
-      return (
-        "ID: " +
-        c.id +
-        " | " +
-        (c.title ?? "DM") +
-        " " +
-        username
-      ).trim();
+      return ("ID: " + c.id + " | " + c.title + " " + username).trim();
     });
 
-    return { content: [{ type: "text", text: lines.join("\n") }] };
+    return { content: [{ type: "text", text: lines.join("\n") }], fromCache };
   } catch (error) {
     return logAndFormatError(
       "get_contact_chats",
diff --git a/src/lib/mcp/telegram/tools/getContactIds.ts b/src/lib/mcp/telegram/tools/getContactIds.ts
index 8fcb7159d..bc70a59a3 100644
--- a/src/lib/mcp/telegram/tools/getContactIds.ts
+++ b/src/lib/mcp/telegram/tools/getContactIds.ts
@@ -1,13 +1,7 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import bigInt from "big-integer";
-import type { ContactIdEntry } from "../apiResultTypes";
-import { narrow } from "../apiCastHelpers";
-
-type ContactIdResult = number | ContactIdEntry;
+import { getContactIds as getContactIdsApi } from "../api/getContactIds";
 
 export const tool: MCPTool = {
   name: "get_contact_ids",
@@ -20,23 +14,20 @@ export async function getContactIds(
   _context: TelegramMCPContext,
 ): Promise<MCPToolResult> {
   try {
-    const client = mtprotoService.getClient();
+    const { data: ids, fromCache } = await getContactIdsApi();
 
-    const result = await mtprotoService.withFloodWaitHandling(async () => {
-      return client.invoke(new Api.contacts.GetContactIDs({ hash: bigInt(0) }));
-    });
-
-    if (!result || !Array.isArray(result) || result.length === 0) {
-      return { content: [{ type: "text", text: "No contact IDs found." }] };
+    if (ids.length === 0) {
+      return {
+        content: [{ type: "text", text: "No contact IDs found." }],
+        fromCache,
+      };
     }
 
-    const ids = narrow<ContactIdResult[]>(result).map((c) =>
-      String(typeof c === "number" ? c : (c.userId ?? c)),
-    );
     return {
       content: [
-        { type: "text", text: ids.length + " contacts:\n" + ids.join("\n") },
+        { type: "text", text: `${ids.length} contacts:\n${ids.join("\n")}` },
       ],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/getDirectChatByContact.ts b/src/lib/mcp/telegram/tools/getDirectChatByContact.ts
index 391ee34c3..28a82fb25 100644
--- a/src/lib/mcp/telegram/tools/getDirectChatByContact.ts
+++ b/src/lib/mcp/telegram/tools/getDirectChatByContact.ts
@@ -2,8 +2,7 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { validateId } from "../../validation";
-import { store } from "../../../../store";
-import { selectOrderedChats } from "../../../../store/telegramSelectors";
+import { getDirectChatByContact as getDirectChatApi } from "../api/getDirectChatByContact";
 
 export const tool: MCPTool = {
   name: "get_direct_chat_by_contact",
@@ -23,21 +22,14 @@ export async function getDirectChatByContact(
 ): Promise<MCPToolResult> {
   try {
     const userId = validateId(args.user_id, "user_id");
-    const state = store.getState();
-    const chats = selectOrderedChats(state);
-
-    const dmChat = chats.find(
-      (c) => c.type === "private" && String(c.id) === String(userId),
-    );
+    const { data: dmChat, fromCache } = await getDirectChatApi(userId);
 
     if (!dmChat) {
       return {
         content: [
-          {
-            type: "text",
-            text: "No direct chat found with user " + userId + ".",
-          },
+          { type: "text", text: "No direct chat found with user " + userId + "." },
         ],
+        fromCache,
       };
     }
 
@@ -45,15 +37,10 @@ export async function getDirectChatByContact(
       content: [
         {
           type: "text",
-          text:
-            "Chat ID: " +
-            dmChat.id +
-            " | Title: " +
-            (dmChat.title ?? "DM") +
-            " | Username: " +
-            (dmChat.username ?? "N/A"),
+          text: "Chat ID: " + dmChat.id + " | Title: " + dmChat.title + " | Username: " + (dmChat.username ?? "N/A"),
         },
       ],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/getDrafts.ts b/src/lib/mcp/telegram/tools/getDrafts.ts
index 0dd351ec4..10491dc80 100644
--- a/src/lib/mcp/telegram/tools/getDrafts.ts
+++ b/src/lib/mcp/telegram/tools/getDrafts.ts
@@ -1,10 +1,7 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import type { UpdatesResult } from "../apiResultTypes";
-import { narrow } from "../apiCastHelpers";
+import { getDrafts as getDraftsApi } from "../api/getDrafts";
 
 export const tool: MCPTool = {
   name: "get_drafts",
@@ -17,34 +14,21 @@ export async function getDrafts(
   _context: TelegramMCPContext,
 ): Promise<MCPToolResult> {
   try {
-    const client = mtprotoService.getClient();
+    const { data: drafts, fromCache } = await getDraftsApi();
 
-    const result = await mtprotoService.withFloodWaitHandling(async () => {
-      return client.invoke(new Api.messages.GetAllDrafts());
-    });
-
-    const updates = narrow<UpdatesResult>(result);
-    if (!updates || !updates.updates || updates.updates.length === 0) {
-      return { content: [{ type: "text", text: "No drafts found." }] };
+    if (drafts.length === 0) {
+      return {
+        content: [{ type: "text", text: "No drafts found." }],
+        fromCache,
+      };
     }
 
-    const lines: string[] = [];
-    for (const update of updates.updates) {
-      if (update.draft && update.draft.message) {
-        const peerId =
-          update.peer?.userId ??
-          update.peer?.chatId ??
-          update.peer?.channelId ??
-          "?";
-        lines.push("Peer " + peerId + ": " + update.draft.message);
-      }
-    }
+    const lines = drafts.map((d) => "Peer " + d.peerId + ": " + d.message);
 
-    if (lines.length === 0) {
-      return { content: [{ type: "text", text: "No drafts found." }] };
-    }
-
-    return { content: [{ type: "text", text: lines.join("\n") }] };
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      fromCache,
+    };
   } catch (error) {
     return logAndFormatError(
       "get_drafts",
diff --git a/src/lib/mcp/telegram/tools/getGifSearch.ts b/src/lib/mcp/telegram/tools/getGifSearch.ts
index e5025b0ce..e477759db 100644
--- a/src/lib/mcp/telegram/tools/getGifSearch.ts
+++ b/src/lib/mcp/telegram/tools/getGifSearch.ts
@@ -1,11 +1,8 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
 import { optNumber } from "../args";
-import type { InlineBotResults } from "../apiResultTypes";
-import { toInputUser, narrow } from "../apiCastHelpers";
+import { getGifSearch as getGifSearchApi } from "../api/getGifSearch";
 
 export const tool: MCPTool = {
   name: "get_gif_search",
@@ -33,31 +30,16 @@ export async function getGifSearch(
       };
     const limit = optNumber(args, "limit", 10);
 
-    const client = mtprotoService.getClient();
+    const { data: gifs, fromCache } = await getGifSearchApi(query, limit);
 
-    const result = await mtprotoService.withFloodWaitHandling(async () => {
-      const bot = await client.getInputEntity("gif");
-      return client.invoke(
-        new Api.messages.GetInlineBotResults({
-          bot: toInputUser(bot),
-          peer: new Api.InputPeerSelf(),
-          query,
-          offset: "",
-        }),
-      );
-    });
-
-    const results = narrow<InlineBotResults>(result)?.results;
-    if (!results || !Array.isArray(results) || results.length === 0) {
+    if (gifs.length === 0) {
       return {
         content: [{ type: "text", text: "No GIFs found for: " + query }],
+        fromCache,
       };
     }
 
-    const lines = results.slice(0, limit).map((r, i: number) => {
-      const title = r.title ?? r.description ?? "GIF " + (i + 1);
-      return i + 1 + ". " + title;
-    });
+    const lines = gifs.map((g, i) => i + 1 + ". " + g.title);
 
     return {
       content: [
@@ -66,6 +48,7 @@ export async function getGifSearch(
           text: lines.length + " GIFs found:\n" + lines.join("\n"),
         },
       ],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/getHistory.ts b/src/lib/mcp/telegram/tools/getHistory.ts
index d1b811578..a36bc42f6 100644
--- a/src/lib/mcp/telegram/tools/getHistory.ts
+++ b/src/lib/mcp/telegram/tools/getHistory.ts
@@ -1,7 +1,8 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { getChatById, getMessagesWithApiFallback, formatMessage } from "../telegramApi";
+import { getMessages as getMessagesApi } from "../api/getMessages";
+import { getChatById, formatMessage } from "../api/helpers";
 import { validateId } from "../../validation";
 import { optNumber } from "../args";
 
@@ -34,10 +35,12 @@ export async function getHistory(
       };
     }
 
-    const messages = await getMessagesWithApiFallback(chatId, limit, 0);
+    const { data: messagesData, fromCache } = await getMessagesApi(chatId, limit, 0);
+    const messages = messagesData.length > 0 ? messagesData : undefined;
     if (!messages || messages.length === 0) {
       return {
         content: [{ type: "text", text: "No messages found in this chat." }],
+        fromCache,
       };
     }
 
@@ -47,7 +50,7 @@ export async function getHistory(
       return `ID: ${f.id} | ${from} | ${f.date} | ${f.text || "[Media/No text]"}`;
     });
 
-    return { content: [{ type: "text", text: lines.join("\n") }] };
+    return { content: [{ type: "text", text: lines.join("\n") }], fromCache };
   } catch (error) {
     return logAndFormatError(
       "get_history",
diff --git a/src/lib/mcp/telegram/tools/getInviteLink.ts b/src/lib/mcp/telegram/tools/getInviteLink.ts
index 347f97931..c23d97372 100644
--- a/src/lib/mcp/telegram/tools/getInviteLink.ts
+++ b/src/lib/mcp/telegram/tools/getInviteLink.ts
@@ -2,11 +2,7 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { validateId } from "../../validation";
-import { getChatById } from "../telegramApi";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import type { ChatInviteResult } from "../apiResultTypes";
-import { narrow } from "../apiCastHelpers";
+import { getInviteLink as getInviteLinkApi } from "../api/getInviteLink";
 
 export const tool: MCPTool = {
   name: "get_invite_link",
@@ -26,36 +22,11 @@ export async function getInviteLink(
 ): Promise<MCPToolResult> {
   try {
     const chatId = validateId(args.chat_id, "chat_id");
-
-    const chat = getChatById(chatId);
-    if (!chat)
-      return {
-        content: [{ type: "text", text: `Chat not found: ${chatId}` }],
-        isError: true,
-      };
-
-    const client = mtprotoService.getClient();
-    const entity = chat.username ? chat.username : chat.id;
-
-    const result = await mtprotoService.withFloodWaitHandling(async () => {
-      const inputPeer = await client.getInputEntity(entity);
-      return client.invoke(
-        new Api.messages.ExportChatInvite({
-          peer: inputPeer,
-          legacyRevokePermanent: true,
-        }),
-      );
-    });
-
-    const link = narrow<ChatInviteResult>(result)?.link;
-    if (!link) {
-      return {
-        content: [{ type: "text", text: "Could not generate invite link." }],
-        isError: true,
-      };
-    }
-
-    return { content: [{ type: "text", text: `Invite link: ${link}` }] };
+    const { data, fromCache } = await getInviteLinkApi(chatId);
+    return {
+      content: [{ type: "text", text: `Invite link: ${data.link}` }],
+      fromCache,
+    };
   } catch (error) {
     return logAndFormatError(
       "get_invite_link",
diff --git a/src/lib/mcp/telegram/tools/getLastInteraction.ts b/src/lib/mcp/telegram/tools/getLastInteraction.ts
index 674ae3b1a..bcd67d224 100644
--- a/src/lib/mcp/telegram/tools/getLastInteraction.ts
+++ b/src/lib/mcp/telegram/tools/getLastInteraction.ts
@@ -2,7 +2,7 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { validateId } from "../../validation";
-import { getChatById, getMessages, formatMessage } from "../telegramApi";
+import { getLastInteraction as getLastInteractionApi } from "../api/getLastInteraction";
 
 export const tool: MCPTool = {
   name: "get_last_interaction",
@@ -22,41 +22,23 @@ export async function getLastInteraction(
 ): Promise<MCPToolResult> {
   try {
     const chatId = validateId(args.chat_id, "chat_id");
+    const { data: interaction, fromCache } = await getLastInteractionApi(chatId);
 
-    const chat = getChatById(chatId);
-    if (!chat) {
-      return {
-        content: [{ type: "text", text: "Chat not found: " + chatId }],
-        isError: true,
-      };
-    }
-
-    const messages = await getMessages(chatId, 1, 0);
-    if (!messages || messages.length === 0) {
+    if (!interaction) {
       return {
         content: [{ type: "text", text: "No messages found in this chat." }],
+        fromCache,
       };
     }
 
-    const msg = messages[0];
-    const f = formatMessage(msg);
-    const from = msg.fromName ?? msg.fromId ?? "Unknown";
-
     return {
       content: [
         {
           type: "text",
-          text:
-            "Last message in " +
-            (chat.title ?? chatId) +
-            ":\nFrom: " +
-            from +
-            " | Date: " +
-            f.date +
-            " | " +
-            (f.text || "[Media/No text]"),
+          text: "Last message in " + interaction.chatTitle + ":\nFrom: " + interaction.from + " | Date: " + interaction.date + " | " + interaction.text,
         },
       ],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/getMe.ts b/src/lib/mcp/telegram/tools/getMe.ts
index 0514fcba0..1b2e4248a 100644
--- a/src/lib/mcp/telegram/tools/getMe.ts
+++ b/src/lib/mcp/telegram/tools/getMe.ts
@@ -6,7 +6,8 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { formatEntity, getCurrentUserWithApiFallback } from "../telegramApi";
+import { getCurrentUser } from "../api/getCurrentUser";
+import { formatEntity } from "../api/helpers";
 
 export const tool: MCPTool = {
   name: "get_me",
@@ -22,11 +23,12 @@ export async function getMe(
   _context: TelegramMCPContext,
 ): Promise<MCPToolResult> {
   try {
-    const user = await getCurrentUserWithApiFallback();
+    const { data: user, fromCache } = await getCurrentUser();
     if (!user) {
       return {
         content: [{ type: "text", text: "User information not available" }],
         isError: true,
+        fromCache,
       };
     }
     const entity = formatEntity(user);
@@ -39,6 +41,7 @@ export async function getMe(
     };
     return {
       content: [{ type: "text", text: JSON.stringify(result, undefined, 2) }],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/getMediaInfo.ts b/src/lib/mcp/telegram/tools/getMediaInfo.ts
index f9687298b..e66d027a8 100644
--- a/src/lib/mcp/telegram/tools/getMediaInfo.ts
+++ b/src/lib/mcp/telegram/tools/getMediaInfo.ts
@@ -2,7 +2,7 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { validateId } from "../../validation";
-import { getChatById, getMessages } from "../telegramApi";
+import { getMediaInfo as getMediaInfoApi } from "../api/getMediaInfo";
 
 export const tool: MCPTool = {
   name: "get_media_info",
@@ -37,43 +37,21 @@ export async function getMediaInfo(
       };
     }
 
-    const chat = getChatById(chatId);
-    if (!chat)
-      return {
-        content: [{ type: "text", text: "Chat not found: " + chatId }],
-        isError: true,
-      };
+    const { data: info, fromCache } = await getMediaInfoApi(chatId, messageId);
 
-    const messages = await getMessages(chatId, 200, 0);
-    if (!messages)
-      return { content: [{ type: "text", text: "No messages found." }] };
-
-    const msg = messages.find((m) => String(m.id) === String(messageId));
-    if (!msg)
-      return {
-        content: [
-          {
-            type: "text",
-            text: "Message " + messageId + " not found in cache.",
-          },
-        ],
-        isError: true,
-      };
-
-    if (!msg.media) {
+    if (info.type === "none") {
       return {
         content: [
           { type: "text", text: "No media in message " + messageId + "." },
         ],
+        fromCache,
       };
     }
 
-    const info = {
-      ...msg.media,
-      type: msg.media.type ?? "unknown",
+    return {
+      content: [{ type: "text", text: JSON.stringify(info, null, 2) }],
+      fromCache,
     };
-
-    return { content: [{ type: "text", text: JSON.stringify(info, null, 2) }] };
   } catch (error) {
     return logAndFormatError(
       "get_media_info",
diff --git a/src/lib/mcp/telegram/tools/getMessageContext.ts b/src/lib/mcp/telegram/tools/getMessageContext.ts
index eeccb7c49..abecc7687 100644
--- a/src/lib/mcp/telegram/tools/getMessageContext.ts
+++ b/src/lib/mcp/telegram/tools/getMessageContext.ts
@@ -1,7 +1,8 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { getChatById, getMessagesWithApiFallback, formatMessage } from "../telegramApi";
+import { getMessages as getMessagesApi } from "../api/getMessages";
+import { getChatById, formatMessage } from "../api/helpers";
 import { validateId } from "../../validation";
 import { optNumber } from "../args";
 
@@ -52,10 +53,12 @@ export async function getMessageContext(
       };
     }
 
-    const allMessages = await getMessagesWithApiFallback(chatId, 200, 0);
+    const { data: allMessagesData, fromCache } = await getMessagesApi(chatId, 200, 0);
+    const allMessages = allMessagesData.length > 0 ? allMessagesData : undefined;
     if (!allMessages || allMessages.length === 0) {
       return {
         content: [{ type: "text", text: "No messages found in this chat." }],
+        fromCache,
       };
     }
 
@@ -85,7 +88,7 @@ export async function getMessageContext(
       return `${marker}ID: ${f.id} | ${from} | ${f.date} | ${f.text || "[Media/No text]"}`;
     });
 
-    return { content: [{ type: "text", text: lines.join("\n") }] };
+    return { content: [{ type: "text", text: lines.join("\n") }], fromCache };
   } catch (error) {
     return logAndFormatError(
       "get_message_context",
diff --git a/src/lib/mcp/telegram/tools/getMessageReactions.ts b/src/lib/mcp/telegram/tools/getMessageReactions.ts
index 69efde804..50b11b234 100644
--- a/src/lib/mcp/telegram/tools/getMessageReactions.ts
+++ b/src/lib/mcp/telegram/tools/getMessageReactions.ts
@@ -1,12 +1,8 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { validateId } from "../../validation";
-import { getChatById } from "../telegramApi";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import type { UpdatesResult } from "../apiResultTypes";
-import { narrow } from "../apiCastHelpers";
+import { validateId, validatePositiveInt } from "../../validation";
+import { getMessageReactions as getMessageReactionsApi } from "../api/getMessageReactions";
 
 export const tool: MCPTool = {
   name: "get_message_reactions",
@@ -27,42 +23,11 @@ export async function getMessageReactions(
 ): Promise<MCPToolResult> {
   try {
     const chatId = validateId(args.chat_id, "chat_id");
-    const messageId =
-      typeof args.message_id === "number" && Number.isInteger(args.message_id)
-        ? args.message_id
-        : undefined;
+    const messageId = validatePositiveInt(args.message_id, "message_id");
 
-    if (messageId === undefined) {
-      return {
-        content: [
-          { type: "text", text: "message_id must be a positive integer" },
-        ],
-        isError: true,
-      };
-    }
+    const { data: reactions, fromCache } = await getMessageReactionsApi(chatId, messageId);
 
-    const chat = getChatById(chatId);
-    if (!chat)
-      return {
-        content: [{ type: "text", text: "Chat not found: " + chatId }],
-        isError: true,
-      };
-
-    const client = mtprotoService.getClient();
-    const entity = chat.username ? chat.username : chat.id;
-
-    const result = await mtprotoService.withFloodWaitHandling(async () => {
-      const inputPeer = await client.getInputEntity(entity);
-      return client.invoke(
-        new Api.messages.GetMessagesReactions({
-          peer: inputPeer,
-          id: [messageId],
-        }),
-      );
-    });
-
-    const updates = narrow<UpdatesResult>(result);
-    if (!updates || !updates.updates || updates.updates.length === 0) {
+    if (reactions.length === 0) {
       return {
         content: [
           {
@@ -70,30 +35,11 @@ export async function getMessageReactions(
             text: "No reactions found on message " + messageId + ".",
           },
         ],
+        fromCache,
       };
     }
 
-    const lines: string[] = [];
-    for (const update of updates.updates) {
-      if (update.reactions && update.reactions.results) {
-        for (const r of update.reactions.results) {
-          const emoji = r.reaction?.emoticon ?? r.reaction?.className ?? "?";
-          const count = r.count ?? 0;
-          lines.push(emoji + ": " + count);
-        }
-      }
-    }
-
-    if (lines.length === 0) {
-      return {
-        content: [
-          {
-            type: "text",
-            text: "No reactions found on message " + messageId + ".",
-          },
-        ],
-      };
-    }
+    const lines = reactions.map((r) => r.emoji + ": " + r.count);
 
     return {
       content: [
@@ -102,6 +48,7 @@ export async function getMessageReactions(
           text: "Reactions on message " + messageId + ":\n" + lines.join("\n"),
         },
       ],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/getMessages.ts b/src/lib/mcp/telegram/tools/getMessages.ts
index 1c3fece64..7994caebb 100644
--- a/src/lib/mcp/telegram/tools/getMessages.ts
+++ b/src/lib/mcp/telegram/tools/getMessages.ts
@@ -6,11 +6,8 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import {
-  formatMessage,
-  getChatById,
-  getMessagesWithApiFallback,
-} from "../telegramApi";
+import { getMessages as getMessagesApi } from "../api/getMessages";
+import { getChatById, formatMessage } from "../api/helpers";
 import { validateId } from "../../validation";
 import type { TelegramMessage } from "../../../../store/telegram/types";
 import { optNumber } from "../args";
@@ -62,10 +59,12 @@ export async function getMessages(
       };
     }
 
-    const messages = await getMessagesWithApiFallback(chatId, pageSize, offset);
+    const { data: messagesData, fromCache } = await getMessagesApi(chatId, pageSize, offset);
+    const messages = messagesData.length > 0 ? messagesData : undefined;
     if (!messages || messages.length === 0) {
       return {
         content: [{ type: "text", text: "No messages found for this page." }],
+        fromCache,
       };
     }
 
@@ -78,7 +77,7 @@ export async function getMessages(
       return `ID: ${formatted.id} | ${senderDisplay(msg)} | Date: ${formatted.date}${replyStr} | Message: ${msgText}`;
     });
 
-    return { content: [{ type: "text", text: lines.join("\n") }] };
+    return { content: [{ type: "text", text: lines.join("\n") }], fromCache };
   } catch (error) {
     return logAndFormatError(
       "get_messages",
diff --git a/src/lib/mcp/telegram/tools/getParticipants.ts b/src/lib/mcp/telegram/tools/getParticipants.ts
index d9a841f35..0f552b043 100644
--- a/src/lib/mcp/telegram/tools/getParticipants.ts
+++ b/src/lib/mcp/telegram/tools/getParticipants.ts
@@ -2,13 +2,8 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { validateId } from "../../validation";
-import { getChatById } from "../telegramApi";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
 import { optNumber } from "../args";
-import bigInt from "big-integer";
-import type { ApiUser } from "../apiResultTypes";
-import { toInputChannel, narrow } from "../apiCastHelpers";
+import { getParticipants as getParticipantsApi } from "../api/getParticipants";
 
 export const tool: MCPTool = {
   name: "get_participants",
@@ -31,54 +26,21 @@ export async function getParticipants(
     const chatId = validateId(args.chat_id, "chat_id");
     const limit = optNumber(args, "limit", 50);
 
-    const chat = getChatById(chatId);
-    if (!chat)
-      return {
-        content: [{ type: "text", text: `Chat not found: ${chatId}` }],
-        isError: true,
-      };
-
-    const client = mtprotoService.getClient();
-    const entity = chat.username ? chat.username : chat.id;
-
-    let participants: ApiUser[] = [];
-
-    if (chat.type === "channel" || chat.type === "supergroup") {
-      const result = await mtprotoService.withFloodWaitHandling(async () => {
-        const inputChannel = await client.getInputEntity(entity);
-        return client.invoke(
-          new Api.channels.GetParticipants({
-            channel: toInputChannel(inputChannel),
-            filter: new Api.ChannelParticipantsRecent(),
-            offset: 0,
-            limit,
-            hash: bigInt(0),
-          }),
-        );
-      });
-      if (result && "users" in result && Array.isArray(result.users)) {
-        participants = narrow<ApiUser[]>(result.users);
-      }
-    } else {
-      const result = await mtprotoService.withFloodWaitHandling(async () => {
-        return client.invoke(
-          new Api.messages.GetFullChat({ chatId: bigInt(chat.id) }),
-        );
-      });
-      if (result && "users" in result && Array.isArray(result.users)) {
-        participants = narrow<ApiUser[]>(result.users);
-      }
-    }
+    const { data: participants, fromCache } = await getParticipantsApi(
+      chatId,
+      limit,
+    );
 
     if (participants.length === 0) {
-      return { content: [{ type: "text", text: "No participants found." }] };
+      return {
+        content: [{ type: "text", text: "No participants found." }],
+        fromCache,
+      };
     }
 
-    const lines = participants.map((u: ApiUser) => {
-      const name =
-        [u.firstName, u.lastName].filter(Boolean).join(" ") || "Unknown";
-      const username = u.username ? `@${u.username}` : "";
-      return `ID: ${u.id} | ${name} ${username}`.trim();
+    const lines = participants.map((p) => {
+      const username = p.username ? `@${p.username}` : "";
+      return `ID: ${p.id} | ${p.name} ${username}`.trim();
     });
 
     return {
@@ -88,6 +50,7 @@ export async function getParticipants(
           text: `${lines.length} participants:\n${lines.join("\n")}`,
         },
       ],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/getPinnedMessages.ts b/src/lib/mcp/telegram/tools/getPinnedMessages.ts
index c79b97bda..749c08526 100644
--- a/src/lib/mcp/telegram/tools/getPinnedMessages.ts
+++ b/src/lib/mcp/telegram/tools/getPinnedMessages.ts
@@ -1,13 +1,8 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { getChatById, getMessages, formatMessage } from "../telegramApi";
 import { validateId } from "../../validation";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import bigInt from "big-integer";
-import type { ApiMessage } from "../apiResultTypes";
-import { narrow } from "../apiCastHelpers";
+import { getPinnedMessages as getPinnedMessagesApi } from "../api/getPinnedMessages";
 
 export const tool: MCPTool = {
   name: "get_pinned_messages",
@@ -28,64 +23,23 @@ export async function getPinnedMessages(
   try {
     const chatId = validateId(args.chat_id, "chat_id");
 
-    const chat = getChatById(chatId);
-    if (!chat) {
+    const { data: pinnedMessages, fromCache } = await getPinnedMessagesApi(chatId);
+
+    if (pinnedMessages.length === 0) {
       return {
-        content: [{ type: "text", text: `Chat not found: ${chatId}` }],
-        isError: true,
+        content: [{ type: "text", text: "No pinned messages found." }],
+        fromCache,
       };
     }
 
-    const entity = chat.username ? chat.username : chat.id;
-    const client = mtprotoService.getClient();
+    const pinnedLines = pinnedMessages.map(
+      (msg) => `ID: ${msg.id} | Date: ${msg.date} | ${msg.text}`,
+    );
 
-    let pinnedLines: string[] = [];
-
-    try {
-      const inputPeer = await client.getInputEntity(entity);
-      const result = await client.invoke(
-        new Api.messages.Search({
-          peer: inputPeer,
-          q: "",
-          filter: new Api.InputMessagesFilterPinned(),
-          minDate: 0,
-          maxDate: 0,
-          offsetId: 0,
-          addOffset: 0,
-          limit: 50,
-          maxId: 0,
-          minId: 0,
-          hash: bigInt(0),
-        }),
-      );
-
-      if ("messages" in result && Array.isArray(result.messages)) {
-        pinnedLines = narrow<ApiMessage[]>(result.messages).map((msg) => {
-          const id = msg.id ?? "?";
-          const text = msg.message ?? "[Media/No text]";
-          const date = msg.date
-            ? new Date(msg.date * 1000).toISOString()
-            : "unknown";
-          return `ID: ${id} | Date: ${date} | ${text}`;
-        });
-      }
-    } catch {
-      // Fallback: check cached messages for pinned flag
-      const allMessages = await getMessages(chatId, 500, 0);
-      if (allMessages) {
-        const pinned = allMessages.filter((m) => narrow<ApiMessage>(m).pinned);
-        pinnedLines = pinned.map((msg) => {
-          const f = formatMessage(msg);
-          return `ID: ${f.id} | Date: ${f.date} | ${f.text || "[Media/No text]"}`;
-        });
-      }
-    }
-
-    if (pinnedLines.length === 0) {
-      return { content: [{ type: "text", text: "No pinned messages found." }] };
-    }
-
-    return { content: [{ type: "text", text: pinnedLines.join("\n") }] };
+    return {
+      content: [{ type: "text", text: pinnedLines.join("\n") }],
+      fromCache,
+    };
   } catch (error) {
     return logAndFormatError(
       "get_pinned_messages",
diff --git a/src/lib/mcp/telegram/tools/getPrivacySettings.ts b/src/lib/mcp/telegram/tools/getPrivacySettings.ts
index 7fc954c0d..b32588e9d 100644
--- a/src/lib/mcp/telegram/tools/getPrivacySettings.ts
+++ b/src/lib/mcp/telegram/tools/getPrivacySettings.ts
@@ -1,10 +1,7 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import type { PrivacyResult } from "../apiResultTypes";
-import { narrow } from "../apiCastHelpers";
+import { getPrivacySettings as getPrivacySettingsApi } from "../api/getPrivacySettings";
 
 export const tool: MCPTool = {
   name: "get_privacy_settings",
@@ -28,55 +25,33 @@ export async function getPrivacySettings(
 ): Promise<MCPToolResult> {
   try {
     const keyStr = typeof args.key === "string" ? args.key : "last_seen";
-    const client = mtprotoService.getClient();
 
-    const keyMap: Record<string, Api.TypeInputPrivacyKey> = {
-      phone_number: new Api.InputPrivacyKeyPhoneNumber(),
-      last_seen: new Api.InputPrivacyKeyStatusTimestamp(),
-      profile_photo: new Api.InputPrivacyKeyProfilePhoto(),
-      forwards: new Api.InputPrivacyKeyForwards(),
-      phone_call: new Api.InputPrivacyKeyPhoneCall(),
-      chat_invite: new Api.InputPrivacyKeyChatInvite(),
-    };
+    const { data: settings, fromCache } = await getPrivacySettingsApi(keyStr);
 
-    const key = keyMap[keyStr];
-    if (!key) {
+    if (settings.rules.length === 0) {
       return {
         content: [
           {
             type: "text",
-            text:
-              "Unknown privacy key: " +
-              keyStr +
-              ". Valid keys: " +
-              Object.keys(keyMap).join(", "),
+            text: "No privacy rules found for " + settings.key + ".",
           },
         ],
-        isError: true,
+        fromCache,
       };
     }
 
-    const result = await mtprotoService.withFloodWaitHandling(async () => {
-      return client.invoke(new Api.account.GetPrivacy({ key }));
-    });
-
-    const rules = narrow<PrivacyResult>(result)?.rules;
-    if (!rules || !Array.isArray(rules)) {
-      return {
-        content: [
-          { type: "text", text: "No privacy rules found for " + keyStr + "." },
-        ],
-      };
-    }
-
-    const lines = rules.map((r) => r.className ?? "Unknown rule");
     return {
       content: [
         {
           type: "text",
-          text: "Privacy settings for " + keyStr + ":\n" + lines.join("\n"),
+          text:
+            "Privacy settings for " +
+            settings.key +
+            ":\n" +
+            settings.rules.join("\n"),
         },
       ],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/getRecentActions.ts b/src/lib/mcp/telegram/tools/getRecentActions.ts
index 2bc7e77ce..abdb48921 100644
--- a/src/lib/mcp/telegram/tools/getRecentActions.ts
+++ b/src/lib/mcp/telegram/tools/getRecentActions.ts
@@ -2,13 +2,8 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { validateId } from "../../validation";
-import { getChatById } from "../telegramApi";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import bigInt from "big-integer";
 import { optNumber } from "../args";
-import type { AdminLogResult } from "../apiResultTypes";
-import { toInputChannel, narrow } from "../apiCastHelpers";
+import { getRecentActions as getRecentActionsApi } from "../api/getRecentActions";
 
 export const tool: MCPTool = {
   name: "get_recent_actions",
@@ -31,53 +26,24 @@ export async function getRecentActions(
     const chatId = validateId(args.chat_id, "chat_id");
     const limit = optNumber(args, "limit", 20);
 
-    const chat = getChatById(chatId);
-    if (!chat)
-      return {
-        content: [{ type: "text", text: "Chat not found: " + chatId }],
-        isError: true,
-      };
+    const { data: actions, fromCache } = await getRecentActionsApi(
+      chatId,
+      limit,
+    );
 
-    if (chat.type !== "channel" && chat.type !== "supergroup") {
+    if (actions.length === 0) {
       return {
-        content: [
-          {
-            type: "text",
-            text: "Recent actions are only available for channels/supergroups.",
-          },
-        ],
-        isError: true,
+        content: [{ type: "text", text: "No recent actions found." }],
+        fromCache,
       };
     }
 
-    const client = mtprotoService.getClient();
-    const entity = chat.username ? chat.username : chat.id;
+    const lines = actions.map((a) => a.date + " | " + a.action);
 
-    const result = await mtprotoService.withFloodWaitHandling(async () => {
-      const inputChannel = await client.getInputEntity(entity);
-      return client.invoke(
-        new Api.channels.GetAdminLog({
-          channel: toInputChannel(inputChannel),
-          q: "",
-          maxId: bigInt(0),
-          minId: bigInt(0),
-          limit,
-        }),
-      );
-    });
-
-    const events = narrow<AdminLogResult>(result)?.events;
-    if (!events || !Array.isArray(events) || events.length === 0) {
-      return { content: [{ type: "text", text: "No recent actions found." }] };
-    }
-
-    const lines = events.map((e) => {
-      const date = e.date ? new Date(e.date * 1000).toISOString() : "unknown";
-      const action = e.action?.className ?? "unknown";
-      return date + " | " + action;
-    });
-
-    return { content: [{ type: "text", text: lines.join("\n") }] };
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      fromCache,
+    };
   } catch (error) {
     return logAndFormatError(
       "get_recent_actions",
diff --git a/src/lib/mcp/telegram/tools/getStickerSets.ts b/src/lib/mcp/telegram/tools/getStickerSets.ts
index eda5236a8..1d867f700 100644
--- a/src/lib/mcp/telegram/tools/getStickerSets.ts
+++ b/src/lib/mcp/telegram/tools/getStickerSets.ts
@@ -1,11 +1,7 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import bigInt from "big-integer";
-import type { StickerSetsResult } from "../apiResultTypes";
-import { narrow } from "../apiCastHelpers";
+import { getStickerSets as getStickerSetsApi } from "../api/getStickerSets";
 
 export const tool: MCPTool = {
   name: "get_sticker_sets",
@@ -18,30 +14,18 @@ export async function getStickerSets(
   _context: TelegramMCPContext,
 ): Promise<MCPToolResult> {
   try {
-    const client = mtprotoService.getClient();
+    const { data: sets, fromCache } = await getStickerSetsApi();
 
-    const result = await mtprotoService.withFloodWaitHandling(async () => {
-      return client.invoke(
-        new Api.messages.GetAllStickers({ hash: bigInt(0) }),
-      );
-    });
-
-    const sets = narrow<StickerSetsResult>(result)?.sets;
-    if (!sets || !Array.isArray(sets) || sets.length === 0) {
-      return { content: [{ type: "text", text: "No sticker sets found." }] };
+    if (sets.length === 0) {
+      return {
+        content: [{ type: "text", text: "No sticker sets found." }],
+        fromCache,
+      };
     }
 
-    const lines = sets.map((s) => {
-      return (
-        "ID: " +
-        s.id +
-        " | " +
-        (s.title ?? "Untitled") +
-        " (" +
-        (s.count ?? 0) +
-        " stickers)"
-      );
-    });
+    const lines = sets.map(
+      (s) => "ID: " + s.id + " | " + s.title + " (" + s.count + " stickers)",
+    );
 
     return {
       content: [
@@ -50,6 +34,7 @@ export async function getStickerSets(
           text: lines.length + " sticker sets:\n" + lines.join("\n"),
         },
       ],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/getUserPhotos.ts b/src/lib/mcp/telegram/tools/getUserPhotos.ts
index 0dcd39d67..882c8c4a8 100644
--- a/src/lib/mcp/telegram/tools/getUserPhotos.ts
+++ b/src/lib/mcp/telegram/tools/getUserPhotos.ts
@@ -2,12 +2,8 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { validateId } from "../../validation";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import bigInt from "big-integer";
 import { optNumber } from "../args";
-import type { ApiPhoto } from "../apiResultTypes";
-import { toInputUser, narrow } from "../apiCastHelpers";
+import { getUserPhotos as getUserPhotosApi } from "../api/getUserPhotos";
 
 export const tool: MCPTool = {
   name: "get_user_photos",
@@ -29,34 +25,15 @@ export async function getUserPhotos(
   try {
     const userId = validateId(args.user_id, "user_id");
     const limit = optNumber(args, "limit", 10);
-    const client = mtprotoService.getClient();
 
-    const result = await mtprotoService.withFloodWaitHandling(async () => {
-      const inputUser = await client.getInputEntity(userId);
-      return client.invoke(
-        new Api.photos.GetUserPhotos({
-          userId: toInputUser(inputUser),
-          offset: 0,
-          maxId: bigInt(0),
-          limit,
-        }),
-      );
-    });
+    const { data: photos, fromCache } = await getUserPhotosApi(userId, limit);
 
-    if (
-      !result ||
-      !("photos" in result) ||
-      !Array.isArray(result.photos) ||
-      result.photos.length === 0
-    ) {
-      return { content: [{ type: "text", text: "No photos found." }] };
+    if (photos.length === 0) {
+      return { content: [{ type: "text", text: "No photos found." }], fromCache };
     }
 
-    const lines = narrow<ApiPhoto[]>(result.photos).map((photo, i: number) => {
-      const date = photo.date
-        ? new Date(photo.date * 1000).toISOString()
-        : "unknown";
-      return "Photo " + (i + 1) + ": ID " + photo.id + " | Date: " + date;
+    const lines = photos.map((photo, i: number) => {
+      return "Photo " + (i + 1) + ": ID " + photo.id + " | Date: " + photo.date;
     });
 
     return {
@@ -66,6 +43,7 @@ export async function getUserPhotos(
           text: lines.length + " photos found:\n" + lines.join("\n"),
         },
       ],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/getUserStatus.ts b/src/lib/mcp/telegram/tools/getUserStatus.ts
index 77fd8e71b..f53c1e6d5 100644
--- a/src/lib/mcp/telegram/tools/getUserStatus.ts
+++ b/src/lib/mcp/telegram/tools/getUserStatus.ts
@@ -2,10 +2,7 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { validateId } from "../../validation";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import type { ApiUser } from "../apiResultTypes";
-import { toInputUser, narrow } from "../apiCastHelpers";
+import { getUserStatus as getUserStatusApi } from "../api/getUserStatus";
 
 export const tool: MCPTool = {
   name: "get_user_status",
@@ -25,47 +22,27 @@ export async function getUserStatus(
 ): Promise<MCPToolResult> {
   try {
     const userId = validateId(args.user_id, "user_id");
-    const client = mtprotoService.getClient();
 
-    const result = await mtprotoService.withFloodWaitHandling(async () => {
-      const inputUser = await client.getInputEntity(userId);
-      return client.invoke(
-        new Api.users.GetUsers({ id: [toInputUser(inputUser)] }),
-      );
-    });
+    const { data: userStatus, fromCache } = await getUserStatusApi(userId);
 
-    if (!result || !Array.isArray(result) || result.length === 0) {
-      return {
-        content: [{ type: "text", text: "User " + userId + " not found." }],
-        isError: true,
-      };
-    }
-
-    const user = narrow<ApiUser>(result[0]);
-    const name =
-      [user.firstName, user.lastName].filter(Boolean).join(" ") || "Unknown";
-    let statusText = "unknown";
-
-    if (user.status) {
-      const s = user.status;
-      if (s.className === "UserStatusOnline") statusText = "Online";
-      else if (s.className === "UserStatusOffline")
-        statusText =
-          "Offline (last seen: " +
-          (s.wasOnline
-            ? new Date(s.wasOnline * 1000).toISOString()
-            : "unknown") +
-          ")";
-      else if (s.className === "UserStatusRecently") statusText = "Recently";
-      else if (s.className === "UserStatusLastWeek") statusText = "Last week";
-      else if (s.className === "UserStatusLastMonth") statusText = "Last month";
-      else statusText = s.className ?? "unknown";
+    let statusText = userStatus.status;
+    if (userStatus.lastSeen) {
+      statusText += " (last seen: " + userStatus.lastSeen + ")";
     }
 
     return {
       content: [
-        { type: "text", text: name + " (ID: " + user.id + "): " + statusText },
+        {
+          type: "text",
+          text:
+            userStatus.name +
+            " (ID: " +
+            userStatus.userId +
+            "): " +
+            statusText,
+        },
       ],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/importChatInvite.ts b/src/lib/mcp/telegram/tools/importChatInvite.ts
index 44fa8c357..1a7380720 100644
--- a/src/lib/mcp/telegram/tools/importChatInvite.ts
+++ b/src/lib/mcp/telegram/tools/importChatInvite.ts
@@ -1,10 +1,7 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import type { ResultWithChats } from "../apiResultTypes";
-import { narrow } from "../apiCastHelpers";
+import { importChatInvite as importChatInviteApi } from "../api/importChatInvite";
 
 export const tool: MCPTool = {
   name: "import_chat_invite",
@@ -33,15 +30,11 @@ export async function importChatInvite(
         isError: true,
       };
 
-    const client = mtprotoService.getClient();
-
-    const result = await mtprotoService.withFloodWaitHandling(async () => {
-      return client.invoke(new Api.messages.ImportChatInvite({ hash }));
-    });
-
-    const chatTitle =
-      narrow<ResultWithChats>(result)?.chats?.[0]?.title ?? "unknown";
-    return { content: [{ type: "text", text: `Joined chat: ${chatTitle}` }] };
+    const { data, fromCache } = await importChatInviteApi(hash);
+    return {
+      content: [{ type: "text", text: `Joined chat: ${data.chatTitle}` }],
+      fromCache,
+    };
   } catch (error) {
     return logAndFormatError(
       "import_chat_invite",
diff --git a/src/lib/mcp/telegram/tools/importContacts.ts b/src/lib/mcp/telegram/tools/importContacts.ts
index 978230ab5..f32c6fd73 100644
--- a/src/lib/mcp/telegram/tools/importContacts.ts
+++ b/src/lib/mcp/telegram/tools/importContacts.ts
@@ -1,11 +1,8 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import bigInt from "big-integer";
-import type { ContactInput, ImportContactsResult } from "../apiResultTypes";
-import { narrow } from "../apiCastHelpers";
+import type { ContactInput } from "../api/apiResultTypes";
+import { importContacts as importContactsApi } from "../api/importContacts";
 
 export const tool: MCPTool = {
   name: "import_contacts",
@@ -37,43 +34,19 @@ export async function importContacts(
 ): Promise<MCPToolResult> {
   try {
     const contactsArg = args.contacts;
-    if (!Array.isArray(contactsArg) || contactsArg.length === 0) {
-      return {
-        content: [
-          {
-            type: "text",
-            text: "contacts array is required and must not be empty.",
-          },
-        ],
-        isError: true,
-      };
+    if (!Array.isArray(contactsArg)) {
+      throw new Error("contacts must be an array");
     }
 
-    const inputContacts = contactsArg.map(
-      (c: ContactInput, i: number) =>
-        new Api.InputPhoneContact({
-          clientId: bigInt(i),
-          phone: String(c.phone ?? ""),
-          firstName: String(c.first_name ?? ""),
-          lastName: String(c.last_name ?? ""),
-        }),
+    const { data } = await importContactsApi(
+      contactsArg as ContactInput[],
     );
 
-    const client = mtprotoService.getClient();
-
-    const result = await mtprotoService.withFloodWaitHandling(async () => {
-      return client.invoke(
-        new Api.contacts.ImportContacts({ contacts: inputContacts }),
-      );
-    });
-
-    const imported =
-      narrow<ImportContactsResult>(result)?.imported?.length ?? 0;
     return {
       content: [
         {
           type: "text",
-          text: `Imported ${imported} of ${contactsArg.length} contacts.`,
+          text: `Imported ${data.imported} of ${data.total} contacts.`,
         },
       ],
     };
diff --git a/src/lib/mcp/telegram/tools/inviteToGroup.ts b/src/lib/mcp/telegram/tools/inviteToGroup.ts
index 84224cded..ee56d0fc5 100644
--- a/src/lib/mcp/telegram/tools/inviteToGroup.ts
+++ b/src/lib/mcp/telegram/tools/inviteToGroup.ts
@@ -2,11 +2,8 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { validateId } from "../../validation";
-import { getChatById } from "../telegramApi";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import bigInt from "big-integer";
-import { toInputChannel, toInputUser } from "../apiCastHelpers";
+import { inviteToGroup as inviteToGroupApi } from "../api/inviteToGroup";
+import { getChatById } from "../api/helpers";
 
 export const tool: MCPTool = {
   name: "invite_to_group",
@@ -31,59 +28,18 @@ export async function inviteToGroup(
 ): Promise<MCPToolResult> {
   try {
     const chatId = validateId(args.chat_id, "chat_id");
-    const userIds = Array.isArray(args.user_ids) ? args.user_ids : [];
-    if (userIds.length === 0)
-      return {
-        content: [{ type: "text", text: "user_ids must not be empty" }],
-        isError: true,
-      };
+    const userIds = Array.isArray(args.user_ids)
+      ? args.user_ids.map(String)
+      : [];
+
+    await inviteToGroupApi(chatId, userIds);
 
     const chat = getChatById(chatId);
-    if (!chat)
-      return {
-        content: [{ type: "text", text: `Chat not found: ${chatId}` }],
-        isError: true,
-      };
-
-    const client = mtprotoService.getClient();
-    const entity = chat.username ? chat.username : chat.id;
-
-    const users: Api.TypeInputUser[] = [];
-    for (const uid of userIds) {
-      const inputUser = await client.getInputEntity(String(uid));
-      users.push(toInputUser(inputUser));
-    }
-
-    const inputPeer = await client.getInputEntity(entity);
-
-    if (chat.type === "channel" || chat.type === "supergroup") {
-      await mtprotoService.withFloodWaitHandling(async () => {
-        await client.invoke(
-          new Api.channels.InviteToChannel({
-            channel: toInputChannel(inputPeer),
-            users,
-          }),
-        );
-      });
-    } else {
-      for (const user of users) {
-        await mtprotoService.withFloodWaitHandling(async () => {
-          await client.invoke(
-            new Api.messages.AddChatUser({
-              chatId: bigInt(chat.id),
-              userId: user,
-              fwdLimit: 100,
-            }),
-          );
-        });
-      }
-    }
-
     return {
       content: [
         {
           type: "text",
-          text: `Invited ${userIds.length} user(s) to ${chat.title ?? chatId}.`,
+          text: `Invited ${userIds.length} user(s) to ${chat?.title ?? chatId}.`,
         },
       ],
     };
diff --git a/src/lib/mcp/telegram/tools/joinChatByLink.ts b/src/lib/mcp/telegram/tools/joinChatByLink.ts
index cb7cd04de..b41bbb7c2 100644
--- a/src/lib/mcp/telegram/tools/joinChatByLink.ts
+++ b/src/lib/mcp/telegram/tools/joinChatByLink.ts
@@ -1,10 +1,7 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import type { ResultWithChats } from "../apiResultTypes";
-import { narrow } from "../apiCastHelpers";
+import { joinChatByLink as joinChatByLinkApi } from "../api/joinChatByLink";
 
 export const tool: MCPTool = {
   name: "join_chat_by_link",
@@ -34,22 +31,11 @@ export async function joinChatByLink(
         isError: true,
       };
 
-    // Extract hash from link
-    let hash = link;
-    const plusMatch = link.match(/t\.me\/\+(.+)/);
-    const joinMatch = link.match(/t\.me\/joinchat\/(.+)/);
-    if (plusMatch) hash = plusMatch[1];
-    else if (joinMatch) hash = joinMatch[1];
-
-    const client = mtprotoService.getClient();
-
-    const result = await mtprotoService.withFloodWaitHandling(async () => {
-      return client.invoke(new Api.messages.ImportChatInvite({ hash }));
-    });
-
-    const chatTitle =
-      narrow<ResultWithChats>(result)?.chats?.[0]?.title ?? "unknown";
-    return { content: [{ type: "text", text: `Joined chat: ${chatTitle}` }] };
+    const { data, fromCache } = await joinChatByLinkApi(link);
+    return {
+      content: [{ type: "text", text: `Joined chat: ${data.chatTitle}` }],
+      fromCache,
+    };
   } catch (error) {
     return logAndFormatError(
       "join_chat_by_link",
diff --git a/src/lib/mcp/telegram/tools/leaveChat.ts b/src/lib/mcp/telegram/tools/leaveChat.ts
index 5d7f1512a..a7703846c 100644
--- a/src/lib/mcp/telegram/tools/leaveChat.ts
+++ b/src/lib/mcp/telegram/tools/leaveChat.ts
@@ -2,11 +2,8 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { validateId } from "../../validation";
-import { getChatById } from "../telegramApi";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import bigInt from "big-integer";
-import { toInputChannel } from "../apiCastHelpers";
+import { getChatById } from "../api/helpers";
+import { leaveChat as leaveChatApi } from "../api/leaveChat";
 
 export const tool: MCPTool = {
   name: "leave_chat",
@@ -26,39 +23,11 @@ export async function leaveChat(
 ): Promise<MCPToolResult> {
   try {
     const chatId = validateId(args.chat_id, "chat_id");
-
     const chat = getChatById(chatId);
-    if (!chat)
-      return {
-        content: [{ type: "text", text: `Chat not found: ${chatId}` }],
-        isError: true,
-      };
-
-    const client = mtprotoService.getClient();
-    const entity = chat.username ? chat.username : chat.id;
-
-    if (chat.type === "channel" || chat.type === "supergroup") {
-      await mtprotoService.withFloodWaitHandling(async () => {
-        const inputChannel = await client.getInputEntity(entity);
-        await client.invoke(
-          new Api.channels.LeaveChannel({
-            channel: toInputChannel(inputChannel),
-          }),
-        );
-      });
-    } else {
-      await mtprotoService.withFloodWaitHandling(async () => {
-        await client.invoke(
-          new Api.messages.DeleteChatUser({
-            chatId: bigInt(chat.id),
-            userId: new Api.InputUserSelf(),
-          }),
-        );
-      });
-    }
-
+    const { fromCache } = await leaveChatApi(chatId);
     return {
-      content: [{ type: "text", text: `Left chat ${chat.title ?? chatId}.` }],
+      content: [{ type: "text", text: `Left chat ${chat?.title ?? chatId}.` }],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/listChats.ts b/src/lib/mcp/telegram/tools/listChats.ts
index 526bc26be..7d1263f1d 100644
--- a/src/lib/mcp/telegram/tools/listChats.ts
+++ b/src/lib/mcp/telegram/tools/listChats.ts
@@ -7,7 +7,8 @@ import type { TelegramMCPContext } from "../types";
 
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { optNumber, optString } from "../args";
-import { formatEntity, getChatsWithApiFallback } from "../telegramApi";
+import { getChats as getChatsApi } from "../api/getChats";
+import { formatEntity } from "../api/helpers";
 import { toHumanReadableAction } from "../toolActionParser";
 
 export const tool: MCPTool = {
@@ -40,7 +41,7 @@ export async function listChats(
     const limit = optNumber(args, "limit", 20);
     const chatType = optString(args, "chat_type")?.toLowerCase();
 
-    const chats = await getChatsWithApiFallback(limit);
+    const { data: chats, fromCache } = await getChatsApi(limit);
     const contentItems: Array<{ type: "text"; text: string }> = [];
 
     for (const chat of chats) {
@@ -62,10 +63,11 @@ export async function listChats(
         content: [
           { type: "text", text: "No chats found matching the criteria." },
         ],
+        fromCache,
       };
     }
 
-    return { content: contentItems };
+    return { content: contentItems, fromCache };
   } catch (error) {
     return logAndFormatError(
       "list_chats",
diff --git a/src/lib/mcp/telegram/tools/listContacts.ts b/src/lib/mcp/telegram/tools/listContacts.ts
index 1feb6ab6f..c39dbbc8a 100644
--- a/src/lib/mcp/telegram/tools/listContacts.ts
+++ b/src/lib/mcp/telegram/tools/listContacts.ts
@@ -1,10 +1,7 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import bigInt from "big-integer";
-import type { ApiUser } from "../apiResultTypes";
+import { listContacts as listContactsApi } from "../api/listContacts";
 
 export const tool: MCPTool = {
   name: "list_contacts",
@@ -17,29 +14,25 @@ export async function listContacts(
   _context: TelegramMCPContext,
 ): Promise<MCPToolResult> {
   try {
-    const client = mtprotoService.getClient();
+    const { data: contacts, fromCache } = await listContactsApi();
 
-    const result = await mtprotoService.withFloodWaitHandling(async () => {
-      return client.invoke(new Api.contacts.GetContacts({ hash: bigInt(0) }));
-    });
-
-    if (!result || !("users" in result) || !Array.isArray(result.users)) {
-      return { content: [{ type: "text", text: "No contacts found." }] };
+    if (contacts.length === 0) {
+      return {
+        content: [{ type: "text", text: "No contacts found." }],
+        fromCache,
+      };
     }
 
-    const lines = result.users.map((u: ApiUser) => {
-      const name =
-        [u.firstName, u.lastName].filter(Boolean).join(" ") || "Unknown";
-      const username = u.username ? `@${u.username}` : "";
-      const phone = u.phone ? `+${u.phone}` : "";
-      return `ID: ${u.id} | ${name} ${username} ${phone}`.trim();
+    const lines = contacts.map((c) => {
+      const username = c.username ? `@${c.username}` : "";
+      const phone = c.phone ? `+${c.phone}` : "";
+      return `ID: ${c.id} | ${c.name} ${username} ${phone}`.trim();
     });
 
-    if (lines.length === 0) {
-      return { content: [{ type: "text", text: "No contacts found." }] };
-    }
-
-    return { content: [{ type: "text", text: lines.join("\n") }] };
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      fromCache,
+    };
   } catch (error) {
     return logAndFormatError(
       "list_contacts",
diff --git a/src/lib/mcp/telegram/tools/listInlineButtons.ts b/src/lib/mcp/telegram/tools/listInlineButtons.ts
index 7852fc7f6..9d2120e7f 100644
--- a/src/lib/mcp/telegram/tools/listInlineButtons.ts
+++ b/src/lib/mcp/telegram/tools/listInlineButtons.ts
@@ -2,9 +2,7 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { validateId } from "../../validation";
-import { getChatById, getMessages } from "../telegramApi";
-import type { MessageWithReplyMarkup, ReplyMarkupRow } from "../apiResultTypes";
-import { narrow } from "../apiCastHelpers";
+import { listInlineButtons as listInlineButtonsApi } from "../api/listInlineButtons";
 
 export const tool: MCPTool = {
   name: "list_inline_buttons",
@@ -39,31 +37,9 @@ export async function listInlineButtons(
       };
     }
 
-    const chat = getChatById(chatId);
-    if (!chat)
-      return {
-        content: [{ type: "text", text: "Chat not found: " + chatId }],
-        isError: true,
-      };
+    const { data: buttons, fromCache } = await listInlineButtonsApi(chatId, messageId);
 
-    const messages = await getMessages(chatId, 200, 0);
-    if (!messages)
-      return { content: [{ type: "text", text: "No messages found." }] };
-
-    const found = messages.find((m) => String(m.id) === String(messageId));
-    const msg = found ? narrow<MessageWithReplyMarkup>(found) : undefined;
-    if (!msg)
-      return {
-        content: [
-          {
-            type: "text",
-            text: "Message " + messageId + " not found in cache.",
-          },
-        ],
-        isError: true,
-      };
-
-    if (!msg.replyMarkup || !msg.replyMarkup.rows) {
+    if (buttons.length === 0) {
       return {
         content: [
           {
@@ -71,32 +47,15 @@ export async function listInlineButtons(
             text: "No inline buttons on message " + messageId + ".",
           },
         ],
+        fromCache,
       };
     }
 
-    const lines: string[] = [];
-    msg.replyMarkup.rows.forEach((row: ReplyMarkupRow, ri: number) => {
-      if (row.buttons) {
-        row.buttons.forEach((btn, bi: number) => {
-          lines.push(
-            "Row " + ri + ", Button " + bi + ': "' + (btn.text ?? "?") + '"',
-          );
-        });
-      }
-    });
+    const lines = buttons.map(
+      (b) => "Row " + b.row + ", Button " + b.button + ': "' + b.text + '"',
+    );
 
-    if (lines.length === 0) {
-      return {
-        content: [
-          {
-            type: "text",
-            text: "No inline buttons on message " + messageId + ".",
-          },
-        ],
-      };
-    }
-
-    return { content: [{ type: "text", text: lines.join("\n") }] };
+    return { content: [{ type: "text", text: lines.join("\n") }], fromCache };
   } catch (error) {
     return logAndFormatError(
       "list_inline_buttons",
diff --git a/src/lib/mcp/telegram/tools/listMessages.ts b/src/lib/mcp/telegram/tools/listMessages.ts
index fee0e9466..3c399bfad 100644
--- a/src/lib/mcp/telegram/tools/listMessages.ts
+++ b/src/lib/mcp/telegram/tools/listMessages.ts
@@ -7,11 +7,8 @@ import type { TelegramMCPContext } from "../types";
 
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { optNumber, optString } from "../args";
-import {
-  formatMessage,
-  getChatById,
-  getMessagesWithApiFallback,
-} from "../telegramApi";
+import { getMessages as getMessagesApi } from "../api/getMessages";
+import { getChatById, formatMessage } from "../api/helpers";
 import { validateId } from "../../validation";
 
 export const tool: MCPTool = {
@@ -65,12 +62,14 @@ export async function listMessages(
       };
     }
 
-    let messages = await getMessagesWithApiFallback(chatId, limit * 2, 0);
+    const { data: messagesRaw, fromCache } = await getMessagesApi(chatId, limit * 2, 0);
+    let messages = messagesRaw.length > 0 ? messagesRaw : undefined;
     if (!messages || messages.length === 0) {
       return {
         content: [
           { type: "text", text: "No messages found matching the criteria." },
         ],
+        fromCache,
       };
     }
 
@@ -105,7 +104,7 @@ export async function listMessages(
       return { type: "text" as const, text };
     });
 
-    return { content: contentItems };
+    return { content: contentItems, fromCache };
   } catch (error) {
     return logAndFormatError(
       "list_messages",
diff --git a/src/lib/mcp/telegram/tools/listTopics.ts b/src/lib/mcp/telegram/tools/listTopics.ts
index f64b565a9..edc36459e 100644
--- a/src/lib/mcp/telegram/tools/listTopics.ts
+++ b/src/lib/mcp/telegram/tools/listTopics.ts
@@ -2,11 +2,7 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { validateId } from "../../validation";
-import { getChatById } from "../telegramApi";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import type { ForumTopicsResult } from "../apiResultTypes";
-import { toInputChannel, narrow } from "../apiCastHelpers";
+import { listTopics as listTopicsApi } from "../api/listTopics";
 
 export const tool: MCPTool = {
   name: "list_topics",
@@ -27,51 +23,21 @@ export async function listTopics(
   try {
     const chatId = validateId(args.chat_id, "chat_id");
 
-    const chat = getChatById(chatId);
-    if (!chat)
-      return {
-        content: [{ type: "text", text: "Chat not found: " + chatId }],
-        isError: true,
-      };
+    const { data: topics, fromCache } = await listTopicsApi(chatId);
 
-    if (chat.type !== "channel" && chat.type !== "supergroup") {
+    if (topics.length === 0) {
       return {
-        content: [
-          {
-            type: "text",
-            text: "Forum topics are only available for channels/supergroups.",
-          },
-        ],
-        isError: true,
+        content: [{ type: "text", text: "No forum topics found." }],
+        fromCache,
       };
     }
 
-    const client = mtprotoService.getClient();
-    const entity = chat.username ? chat.username : chat.id;
+    const lines = topics.map((t) => "ID: " + t.id + " | " + t.title);
 
-    const result = await mtprotoService.withFloodWaitHandling(async () => {
-      const inputChannel = await client.getInputEntity(entity);
-      return client.invoke(
-        new Api.channels.GetForumTopics({
-          channel: toInputChannel(inputChannel),
-          offsetDate: 0,
-          offsetId: 0,
-          offsetTopic: 0,
-          limit: 100,
-        }),
-      );
-    });
-
-    const topics = narrow<ForumTopicsResult>(result)?.topics;
-    if (!topics || !Array.isArray(topics) || topics.length === 0) {
-      return { content: [{ type: "text", text: "No forum topics found." }] };
-    }
-
-    const lines = topics.map((t) => {
-      return "ID: " + t.id + " | " + (t.title ?? "Untitled");
-    });
-
-    return { content: [{ type: "text", text: lines.join("\n") }] };
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      fromCache,
+    };
   } catch (error) {
     return logAndFormatError(
       "list_topics",
diff --git a/src/lib/mcp/telegram/tools/markAsRead.ts b/src/lib/mcp/telegram/tools/markAsRead.ts
index c0de621a0..cb2619b63 100644
--- a/src/lib/mcp/telegram/tools/markAsRead.ts
+++ b/src/lib/mcp/telegram/tools/markAsRead.ts
@@ -1,9 +1,8 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { getChatById } from "../telegramApi";
 import { validateId } from "../../validation";
-import { mtprotoService } from "../../../../services/mtprotoService";
+import { markAsRead as markAsReadApi } from "../api/markAsRead";
 
 export const tool: MCPTool = {
   name: "mark_as_read",
@@ -24,25 +23,13 @@ export async function markAsRead(
   try {
     const chatId = validateId(args.chat_id, "chat_id");
 
-    const chat = getChatById(chatId);
-    if (!chat) {
-      return {
-        content: [{ type: "text", text: `Chat not found: ${chatId}` }],
-        isError: true,
-      };
-    }
-
-    const entity = chat.username ? chat.username : chat.id;
-    const client = mtprotoService.getClient();
-
-    await mtprotoService.withFloodWaitHandling(async () => {
-      await client.markAsRead(entity);
-    });
+    const { fromCache } = await markAsReadApi(chatId);
 
     return {
       content: [
         { type: "text", text: `Messages in chat ${chatId} marked as read.` },
       ],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/muteChat.ts b/src/lib/mcp/telegram/tools/muteChat.ts
index 275e1109a..bf069e246 100644
--- a/src/lib/mcp/telegram/tools/muteChat.ts
+++ b/src/lib/mcp/telegram/tools/muteChat.ts
@@ -2,9 +2,7 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { validateId } from "../../validation";
-import { getChatById } from "../telegramApi";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
+import { muteChat as muteChatApi } from "../api/muteChat";
 
 export const tool: MCPTool = {
   name: "mute_chat",
@@ -30,33 +28,11 @@ export async function muteChat(
   try {
     const chatId = validateId(args.chat_id, "chat_id");
     const duration = typeof args.duration === "number" ? args.duration : 0;
-
-    const chat = getChatById(chatId);
-    if (!chat)
-      return {
-        content: [{ type: "text", text: `Chat not found: ${chatId}` }],
-        isError: true,
-      };
-
-    const client = mtprotoService.getClient();
-    const entity = chat.username ? chat.username : chat.id;
-
-    const muteUntil =
-      duration === 0 ? 2147483647 : Math.floor(Date.now() / 1000) + duration;
-
-    await mtprotoService.withFloodWaitHandling(async () => {
-      const inputPeer = await client.getInputEntity(entity);
-      await client.invoke(
-        new Api.account.UpdateNotifySettings({
-          peer: new Api.InputNotifyPeer({ peer: inputPeer }),
-          settings: new Api.InputPeerNotifySettings({
-            muteUntil,
-          }),
-        }),
-      );
-    });
-
-    return { content: [{ type: "text", text: `Chat ${chatId} muted.` }] };
+    const { fromCache } = await muteChatApi(chatId, duration);
+    return {
+      content: [{ type: "text", text: `Chat ${chatId} muted.` }],
+      fromCache,
+    };
   } catch (error) {
     return logAndFormatError(
       "mute_chat",
diff --git a/src/lib/mcp/telegram/tools/pinMessage.ts b/src/lib/mcp/telegram/tools/pinMessage.ts
index 7e0c67597..7eaf29607 100644
--- a/src/lib/mcp/telegram/tools/pinMessage.ts
+++ b/src/lib/mcp/telegram/tools/pinMessage.ts
@@ -1,9 +1,8 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { getChatById } from "../telegramApi";
-import { validateId } from "../../validation";
-import { mtprotoService } from "../../../../services/mtprotoService";
+import { validateId, validatePositiveInt } from "../../validation";
+import { pinMessage as pinMessageApi } from "../api/pinMessage";
 
 export const tool: MCPTool = {
   name: "pin_message",
@@ -24,34 +23,9 @@ export async function pinMessage(
 ): Promise<MCPToolResult> {
   try {
     const chatId = validateId(args.chat_id, "chat_id");
-    const messageId =
-      typeof args.message_id === "number" && Number.isInteger(args.message_id)
-        ? args.message_id
-        : undefined;
+    const messageId = validatePositiveInt(args.message_id, "message_id");
 
-    if (messageId === undefined) {
-      return {
-        content: [
-          { type: "text", text: "message_id must be a positive integer" },
-        ],
-        isError: true,
-      };
-    }
-
-    const chat = getChatById(chatId);
-    if (!chat) {
-      return {
-        content: [{ type: "text", text: `Chat not found: ${chatId}` }],
-        isError: true,
-      };
-    }
-
-    const entity = chat.username ? chat.username : chat.id;
-    const client = mtprotoService.getClient();
-
-    await mtprotoService.withFloodWaitHandling(async () => {
-      await client.pinMessage(entity, messageId, { notify: false });
-    });
+    const { fromCache } = await pinMessageApi(chatId, messageId);
 
     return {
       content: [
@@ -60,6 +34,7 @@ export async function pinMessage(
           text: `Message ${messageId} pinned in chat ${chatId}.`,
         },
       ],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/pressInlineButton.ts b/src/lib/mcp/telegram/tools/pressInlineButton.ts
index fb8759483..c1ca0ce2c 100644
--- a/src/lib/mcp/telegram/tools/pressInlineButton.ts
+++ b/src/lib/mcp/telegram/tools/pressInlineButton.ts
@@ -1,12 +1,8 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { validateId } from "../../validation";
-import { getChatById } from "../telegramApi";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import type { BotCallbackAnswer } from "../apiResultTypes";
-import { narrow } from "../apiCastHelpers";
+import { validateId, validatePositiveInt } from "../../validation";
+import { pressInlineButton as pressInlineButtonApi } from "../api/pressInlineButton";
 
 export const tool: MCPTool = {
   name: "press_inline_button",
@@ -28,51 +24,21 @@ export async function pressInlineButton(
 ): Promise<MCPToolResult> {
   try {
     const chatId = validateId(args.chat_id, "chat_id");
-    const messageId =
-      typeof args.message_id === "number" && Number.isInteger(args.message_id)
-        ? args.message_id
-        : undefined;
+    const messageId = validatePositiveInt(args.message_id, "message_id");
     const data = typeof args.button_text === "string" ? args.button_text : "";
 
-    if (messageId === undefined) {
-      return {
-        content: [
-          { type: "text", text: "message_id must be a positive integer" },
-        ],
-        isError: true,
-      };
-    }
     if (!data)
       return {
         content: [{ type: "text", text: "button_text is required" }],
         isError: true,
       };
 
-    const chat = getChatById(chatId);
-    if (!chat)
-      return {
-        content: [{ type: "text", text: "Chat not found: " + chatId }],
-        isError: true,
-      };
+    const { data: answer, fromCache } = await pressInlineButtonApi(chatId, messageId, data);
 
-    const client = mtprotoService.getClient();
-    const entity = chat.username ? chat.username : chat.id;
-
-    const result = await mtprotoService.withFloodWaitHandling(async () => {
-      const inputPeer = await client.getInputEntity(entity);
-      return client.invoke(
-        new Api.messages.GetBotCallbackAnswer({
-          peer: inputPeer,
-          msgId: messageId,
-          data: Buffer.from(data, "base64"),
-        }),
-      );
-    });
-
-    const answer =
-      narrow<BotCallbackAnswer>(result)?.message ??
-      "Button pressed (no response message).";
-    return { content: [{ type: "text", text: answer }] };
+    return {
+      content: [{ type: "text", text: answer }],
+      fromCache,
+    };
   } catch (error) {
     return logAndFormatError(
       "press_inline_button",
diff --git a/src/lib/mcp/telegram/tools/promoteAdmin.ts b/src/lib/mcp/telegram/tools/promoteAdmin.ts
index 829bdebf2..865ae48f2 100644
--- a/src/lib/mcp/telegram/tools/promoteAdmin.ts
+++ b/src/lib/mcp/telegram/tools/promoteAdmin.ts
@@ -2,10 +2,8 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { validateId } from "../../validation";
-import { getChatById } from "../telegramApi";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import { toInputChannel, toInputUser } from "../apiCastHelpers";
+import { promoteAdmin as promoteAdminApi } from "../api/promoteAdmin";
+import { getChatById } from "../api/helpers";
 
 export const tool: MCPTool = {
   name: "promote_admin",
@@ -28,53 +26,14 @@ export async function promoteAdmin(
     const chatId = validateId(args.chat_id, "chat_id");
     const userId = validateId(args.user_id, "user_id");
 
+    await promoteAdminApi(chatId, userId);
+
     const chat = getChatById(chatId);
-    if (!chat)
-      return {
-        content: [{ type: "text", text: `Chat not found: ${chatId}` }],
-        isError: true,
-      };
-
-    if (chat.type !== "channel" && chat.type !== "supergroup") {
-      return {
-        content: [
-          {
-            type: "text",
-            text: "Admin promotion is only available for channels/supergroups.",
-          },
-        ],
-        isError: true,
-      };
-    }
-
-    const client = mtprotoService.getClient();
-    const entity = chat.username ? chat.username : chat.id;
-
-    await mtprotoService.withFloodWaitHandling(async () => {
-      const inputChannel = await client.getInputEntity(entity);
-      const inputUser = await client.getInputEntity(userId);
-      await client.invoke(
-        new Api.channels.EditAdmin({
-          channel: toInputChannel(inputChannel),
-          userId: toInputUser(inputUser),
-          adminRights: new Api.ChatAdminRights({
-            changeInfo: true,
-            deleteMessages: true,
-            banUsers: true,
-            inviteUsers: true,
-            pinMessages: true,
-            manageCall: true,
-          }),
-          rank: "Admin",
-        }),
-      );
-    });
-
     return {
       content: [
         {
           type: "text",
-          text: `User ${userId} promoted to admin in ${chat.title ?? chatId}.`,
+          text: `User ${userId} promoted to admin in ${chat?.title ?? chatId}.`,
         },
       ],
     };
diff --git a/src/lib/mcp/telegram/tools/removeReaction.ts b/src/lib/mcp/telegram/tools/removeReaction.ts
index 68b09305e..d1fbe99e1 100644
--- a/src/lib/mcp/telegram/tools/removeReaction.ts
+++ b/src/lib/mcp/telegram/tools/removeReaction.ts
@@ -1,10 +1,8 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { validateId } from "../../validation";
-import { getChatById } from "../telegramApi";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
+import { validateId, validatePositiveInt } from "../../validation";
+import { removeReaction as removeReactionApi } from "../api/removeReaction";
 
 export const tool: MCPTool = {
   name: "remove_reaction",
@@ -26,40 +24,9 @@ export async function removeReaction(
 ): Promise<MCPToolResult> {
   try {
     const chatId = validateId(args.chat_id, "chat_id");
-    const messageId =
-      typeof args.message_id === "number" && Number.isInteger(args.message_id)
-        ? args.message_id
-        : undefined;
+    const messageId = validatePositiveInt(args.message_id, "message_id");
 
-    if (messageId === undefined) {
-      return {
-        content: [
-          { type: "text", text: "message_id must be a positive integer" },
-        ],
-        isError: true,
-      };
-    }
-
-    const chat = getChatById(chatId);
-    if (!chat)
-      return {
-        content: [{ type: "text", text: "Chat not found: " + chatId }],
-        isError: true,
-      };
-
-    const client = mtprotoService.getClient();
-    const entity = chat.username ? chat.username : chat.id;
-
-    await mtprotoService.withFloodWaitHandling(async () => {
-      const inputPeer = await client.getInputEntity(entity);
-      await client.invoke(
-        new Api.messages.SendReaction({
-          peer: inputPeer,
-          msgId: messageId,
-          reaction: [],
-        }),
-      );
-    });
+    const { fromCache } = await removeReactionApi(chatId, messageId);
 
     return {
       content: [
@@ -68,6 +35,7 @@ export async function removeReaction(
           text: "Reaction removed from message " + messageId + ".",
         },
       ],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/replyToMessage.ts b/src/lib/mcp/telegram/tools/replyToMessage.ts
index 00507afea..a141c819d 100644
--- a/src/lib/mcp/telegram/tools/replyToMessage.ts
+++ b/src/lib/mcp/telegram/tools/replyToMessage.ts
@@ -6,7 +6,8 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { getChatById, sendMessage } from "../telegramApi";
+import { sendMessage } from "../api/sendMessage";
+import { getChatById } from "../api/helpers";
 import { toHumanReadableAction } from "../toolActionParser";
 import { validateId } from "../../validation";
 
@@ -62,8 +63,8 @@ export async function replyToMessage(
       };
     }
 
-    const result = await sendMessage(chatId, text, messageId);
-    if (!result) {
+    const { data, fromCache } = await sendMessage(chatId, text, messageId);
+    if (!data) {
       return {
         content: [
           {
@@ -82,6 +83,7 @@ export async function replyToMessage(
           text: `Replied to message ${messageId} in chat ${chatId}.`,
         },
       ],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/resolveUsername.ts b/src/lib/mcp/telegram/tools/resolveUsername.ts
index 61c99db0f..94d323d8b 100644
--- a/src/lib/mcp/telegram/tools/resolveUsername.ts
+++ b/src/lib/mcp/telegram/tools/resolveUsername.ts
@@ -9,9 +9,7 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { formatEntity, getChatById } from "../telegramApi";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
+import { resolveUsername as resolveUsernameApi } from "../api/resolveUsername";
 
 export const tool: MCPTool = {
   name: "resolve_username",
@@ -40,104 +38,27 @@ export async function resolveUsername(
         isError: true,
       };
     }
-    const username = raw.startsWith("@") ? raw.slice(1) : raw;
 
-    // Try server-side resolution via Telegram API
-    try {
-      const client = mtprotoService.getClient();
+    const { data: resolved, fromCache } = await resolveUsernameApi(raw);
 
-      const result = await mtprotoService.withFloodWaitHandling(async () => {
-        return client.invoke(
-          new Api.contacts.ResolveUsername({ username }),
-        );
-      });
-
-      if (result && "peer" in result) {
-        const peer = result.peer;
-        const peerType =
-          peer.className === "PeerUser"
-            ? "user"
-            : peer.className === "PeerChannel"
-              ? "channel"
-              : peer.className === "PeerChat"
-                ? "chat"
-                : "unknown";
-
-        // Extract ID from peer
-        const peerId =
-          "userId" in peer
-            ? String(peer.userId)
-            : "channelId" in peer
-              ? String(peer.channelId)
-              : "chatId" in peer
-                ? String(peer.chatId)
-                : "unknown";
-
-        // Try to get name from resolved users/chats
-        let name = username;
-        if ("users" in result && Array.isArray(result.users)) {
-          const user = result.users[0] as {
-            firstName?: string;
-            lastName?: string;
-          };
-          if (user) {
-            name =
-              [user.firstName, user.lastName].filter(Boolean).join(" ") ||
-              username;
-          }
-        }
-        if ("chats" in result && Array.isArray(result.chats)) {
-          const chat = result.chats[0] as { title?: string };
-          if (chat?.title) {
-            name = chat.title;
-          }
-        }
-
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(
-                { id: peerId, name, type: peerType, username },
-                undefined,
-                2,
-              ),
-            },
-          ],
-        };
-      }
-    } catch {
-      // API call failed — fall back to cached lookup below
-    }
-
-    // Fallback: look up from cached state
-    const lookupKey = `@${username}`;
-    const chat = getChatById(lookupKey);
-    if (!chat) {
+    if (!resolved) {
+      const username = raw.startsWith("@") ? raw : `@${raw}`;
       return {
         content: [
-          { type: "text", text: `Username @${username} not found` },
+          { type: "text", text: `Username ${username} not found` },
         ],
         isError: true,
       };
     }
-    const entity = formatEntity(chat);
+
     return {
       content: [
         {
           type: "text",
-          text: JSON.stringify(
-            {
-              id: entity.id,
-              name: entity.name,
-              type: entity.type,
-              username: entity.username,
-            },
-            undefined,
-            2,
-          ),
+          text: JSON.stringify(resolved, undefined, 2),
         },
       ],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/saveDraft.ts b/src/lib/mcp/telegram/tools/saveDraft.ts
index 7246f13b0..54f740445 100644
--- a/src/lib/mcp/telegram/tools/saveDraft.ts
+++ b/src/lib/mcp/telegram/tools/saveDraft.ts
@@ -2,9 +2,7 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { validateId } from "../../validation";
-import { getChatById } from "../telegramApi";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
+import { saveDraft as saveDraftApi } from "../api/saveDraft";
 
 export const tool: MCPTool = {
   name: "save_draft",
@@ -32,28 +30,11 @@ export async function saveDraft(
         isError: true,
       };
 
-    const chat = getChatById(chatId);
-    if (!chat)
-      return {
-        content: [{ type: "text", text: "Chat not found: " + chatId }],
-        isError: true,
-      };
-
-    const client = mtprotoService.getClient();
-    const entity = chat.username ? chat.username : chat.id;
-
-    await mtprotoService.withFloodWaitHandling(async () => {
-      const inputPeer = await client.getInputEntity(entity);
-      await client.invoke(
-        new Api.messages.SaveDraft({
-          peer: inputPeer,
-          message: text,
-        }),
-      );
-    });
+    const { fromCache } = await saveDraftApi(chatId, text);
 
     return {
       content: [{ type: "text", text: "Draft saved in chat " + chatId + "." }],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/searchContacts.ts b/src/lib/mcp/telegram/tools/searchContacts.ts
index e62871126..5bd7c15f7 100644
--- a/src/lib/mcp/telegram/tools/searchContacts.ts
+++ b/src/lib/mcp/telegram/tools/searchContacts.ts
@@ -1,10 +1,8 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
 import { optNumber } from "../args";
-import type { ApiUser } from "../apiResultTypes";
+import { searchContacts as searchContactsApi } from "../api/searchContacts";
 
 export const tool: MCPTool = {
   name: "search_contacts",
@@ -25,38 +23,29 @@ export async function searchContacts(
 ): Promise<MCPToolResult> {
   try {
     const query = typeof args.query === "string" ? args.query : "";
-    if (!query) {
-      return {
-        content: [{ type: "text", text: "query is required" }],
-        isError: true,
-      };
-    }
     const limit = optNumber(args, "limit", 20);
-    const client = mtprotoService.getClient();
 
-    const result = await mtprotoService.withFloodWaitHandling(async () => {
-      return client.invoke(new Api.contacts.Search({ q: query, limit }));
-    });
+    const { data: contacts, fromCache } = await searchContactsApi(
+      query,
+      limit,
+    );
 
-    if (
-      !result ||
-      !("users" in result) ||
-      !Array.isArray(result.users) ||
-      result.users.length === 0
-    ) {
+    if (contacts.length === 0) {
       return {
         content: [{ type: "text", text: `No contacts found for "${query}".` }],
+        fromCache,
       };
     }
 
-    const lines = result.users.map((u: ApiUser) => {
-      const name =
-        [u.firstName, u.lastName].filter(Boolean).join(" ") || "Unknown";
-      const username = u.username ? `@${u.username}` : "";
-      return `ID: ${u.id} | ${name} ${username}`.trim();
+    const lines = contacts.map((c) => {
+      const username = c.username ? `@${c.username}` : "";
+      return `ID: ${c.id} | ${c.name} ${username}`.trim();
     });
 
-    return { content: [{ type: "text", text: lines.join("\n") }] };
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      fromCache,
+    };
   } catch (error) {
     return logAndFormatError(
       "search_contacts",
diff --git a/src/lib/mcp/telegram/tools/searchMessages.ts b/src/lib/mcp/telegram/tools/searchMessages.ts
index 8f1a4c46c..9c220e415 100644
--- a/src/lib/mcp/telegram/tools/searchMessages.ts
+++ b/src/lib/mcp/telegram/tools/searchMessages.ts
@@ -10,13 +10,8 @@ import type { TelegramMCPContext } from "../types";
 
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { optNumber } from "../args";
-import { formatMessage, getChatById, getMessages } from "../telegramApi";
 import { validateId } from "../../validation";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import bigInt from "big-integer";
-import type { ApiMessage } from "../apiResultTypes";
-import { narrow } from "../apiCastHelpers";
+import { searchMessages as searchMessagesApi } from "../api/searchMessages";
 
 export const tool: MCPTool = {
   name: "search_messages",
@@ -52,92 +47,30 @@ export async function searchMessages(
       };
     }
 
-    const chat = getChatById(chatId);
-    if (!chat) {
-      return {
-        content: [{ type: "text", text: `Chat ${chatId} not found` }],
-        isError: true,
-      };
-    }
+    const { data: messages, fromCache } = await searchMessagesApi(chatId, query, limit);
 
-    // Try server-side search via Telegram API
-    try {
-      const client = mtprotoService.getClient();
-      const entity = chat.username ? chat.username : chat.id;
-      const inputPeer = await client.getInputEntity(entity);
-
-      const result = await mtprotoService.withFloodWaitHandling(async () => {
-        return client.invoke(
-          new Api.messages.Search({
-            peer: inputPeer,
-            q: query,
-            filter: new Api.InputMessagesFilterEmpty(),
-            minDate: 0,
-            maxDate: 0,
-            offsetId: 0,
-            addOffset: 0,
-            limit,
-            maxId: 0,
-            minId: 0,
-            hash: bigInt(0),
-          }),
-        );
-      });
-
-      if ("messages" in result && Array.isArray(result.messages)) {
-        const messages = narrow<ApiMessage[]>(result.messages);
-
-        if (messages.length === 0) {
-          return {
-            content: [
-              { type: "text", text: `No messages matching "${query}" found.` },
-            ],
-          };
-        }
-
-        const lines = messages.map((msg) => {
-          const id = msg.id ?? "?";
-          const text = msg.message ?? "[Media/No text]";
-          const date = msg.date
-            ? new Date(msg.date * 1000).toISOString()
-            : "unknown";
-          return `ID: ${id} | Date: ${date} | ${text}`;
-        });
-
-        return { content: [{ type: "text", text: lines.join("\n") }] };
-      }
-    } catch {
-      // API call failed — fall back to cached message search below
-    }
-
-    // Fallback: search cached messages locally
-    const messages = await getMessages(chatId, Math.min(limit * 3, 100), 0);
-    if (!messages || messages.length === 0) {
-      return { content: [{ type: "text", text: "No messages found." }] };
-    }
-
-    const q = query.toLowerCase();
-    const filtered = messages
-      .filter((m) => (m.message ?? "").toLowerCase().includes(q))
-      .slice(0, limit);
-
-    if (filtered.length === 0) {
+    if (messages.length === 0) {
       return {
         content: [
           { type: "text", text: `No messages matching "${query}" found.` },
         ],
+        fromCache,
       };
     }
 
-    const lines = filtered.map((m) => {
-      const f = formatMessage(m);
-      return `ID: ${f.id} | ${m.fromName ?? m.fromId ?? "Unknown"} | ${f.date} | ${f.text || "[Media]"}`;
+    const lines = messages.map((msg) => {
+      const parts = [`ID: ${msg.id}`, `Date: ${msg.date}`, msg.text];
+      if (msg.from) {
+        parts.splice(1, 0, msg.from);
+      }
+      return parts.join(" | ");
     });
 
+    const prefix = fromCache ? "(cached search)\n" : "";
+
     return {
-      content: [
-        { type: "text", text: `(cached search)\n${lines.join("\n")}` },
-      ],
+      content: [{ type: "text", text: prefix + lines.join("\n") }],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/searchPublicChats.ts b/src/lib/mcp/telegram/tools/searchPublicChats.ts
index 4eec984f1..b7a611577 100644
--- a/src/lib/mcp/telegram/tools/searchPublicChats.ts
+++ b/src/lib/mcp/telegram/tools/searchPublicChats.ts
@@ -7,11 +7,8 @@
 
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
-
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { formatEntity, searchChats } from "../telegramApi";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
+import { searchPublicChats as searchPublicChatsApi } from "../api/searchPublicChats";
 
 export const tool: MCPTool = {
   name: "search_public_chats",
@@ -39,82 +36,7 @@ export async function searchPublicChats(
       };
     }
 
-    // Try server-side search via Telegram API
-    try {
-      const client = mtprotoService.getClient();
-
-      const result = await mtprotoService.withFloodWaitHandling(async () => {
-        return client.invoke(
-          new Api.contacts.Search({ q: query, limit: 20 }),
-        );
-      });
-
-      const entries: Array<{
-        id: string;
-        name: string;
-        type: string;
-        username?: string;
-      }> = [];
-
-      // Process returned chats
-      if ("chats" in result && Array.isArray(result.chats)) {
-        for (const chat of result.chats) {
-          const c = chat as {
-            id: { toString(): string };
-            title?: string;
-            username?: string;
-            megagroup?: boolean;
-            broadcast?: boolean;
-          };
-          const type = c.broadcast
-            ? "channel"
-            : c.megagroup
-              ? "group"
-              : "chat";
-          entries.push({
-            id: String(c.id),
-            name: c.title ?? "Unknown",
-            type,
-            username: c.username,
-          });
-        }
-      }
-
-      // Process returned users
-      if ("users" in result && Array.isArray(result.users)) {
-        for (const user of result.users) {
-          const u = user as {
-            id: { toString(): string };
-            firstName?: string;
-            lastName?: string;
-            username?: string;
-            bot?: boolean;
-          };
-          const name =
-            [u.firstName, u.lastName].filter(Boolean).join(" ") || "Unknown";
-          entries.push({
-            id: String(u.id),
-            name,
-            type: u.bot ? "bot" : "user",
-            username: u.username,
-          });
-        }
-      }
-
-      if (entries.length > 0) {
-        return {
-          content: [
-            { type: "text", text: JSON.stringify(entries, undefined, 2) },
-          ],
-        };
-      }
-    } catch {
-      // API call failed — fall back to cached search below
-    }
-
-    // Fallback: search cached chats locally
-    const chats = await searchChats(query);
-    const results = chats.map(formatEntity);
+    const { data: results, fromCache } = await searchPublicChatsApi(query);
 
     if (results.length === 0) {
       return {
@@ -124,16 +46,19 @@ export async function searchPublicChats(
             text: `No public chats matching "${query}" found.`,
           },
         ],
+        fromCache,
       };
     }
 
+    const prefix = fromCache ? "(cached search)\n" : "";
     return {
       content: [
         {
           type: "text",
-          text: `(cached search)\n${JSON.stringify(results, undefined, 2)}`,
+          text: prefix + JSON.stringify(results, undefined, 2),
         },
       ],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/sendMessage.ts b/src/lib/mcp/telegram/tools/sendMessage.ts
index 2cf4846e7..927f87a5f 100644
--- a/src/lib/mcp/telegram/tools/sendMessage.ts
+++ b/src/lib/mcp/telegram/tools/sendMessage.ts
@@ -6,7 +6,7 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { sendMessage as sendMessageApi } from "../telegramApi";
+import { sendMessage as sendMessageApiCall } from "../api/sendMessage";
 import { toHumanReadableAction } from "../toolActionParser";
 import { validateId } from "../../validation";
 
@@ -40,7 +40,7 @@ export async function sendMessage(
         isError: true,
       };
     }
-    const result = await sendMessageApi(chatId, message);
+    const { data: result, fromCache } = await sendMessageApiCall(chatId, message);
     if (!result) {
       return {
         content: [
@@ -49,7 +49,7 @@ export async function sendMessage(
         isError: true,
       };
     }
-    return { content: [{ type: "text", text: "Message sent successfully." }] };
+    return { content: [{ type: "text", text: "Message sent successfully." }], fromCache };
   } catch (error) {
     return logAndFormatError(
       "send_message",
diff --git a/src/lib/mcp/telegram/tools/sendReaction.ts b/src/lib/mcp/telegram/tools/sendReaction.ts
index 0ea4b42d3..2f4590f73 100644
--- a/src/lib/mcp/telegram/tools/sendReaction.ts
+++ b/src/lib/mcp/telegram/tools/sendReaction.ts
@@ -1,10 +1,8 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { validateId } from "../../validation";
-import { getChatById } from "../telegramApi";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
+import { validateId, validatePositiveInt } from "../../validation";
+import { sendReaction as sendReactionApi } from "../api/sendReaction";
 
 export const tool: MCPTool = {
   name: "send_reaction",
@@ -26,42 +24,11 @@ export async function sendReaction(
 ): Promise<MCPToolResult> {
   try {
     const chatId = validateId(args.chat_id, "chat_id");
-    const messageId =
-      typeof args.message_id === "number" && Number.isInteger(args.message_id)
-        ? args.message_id
-        : undefined;
+    const messageId = validatePositiveInt(args.message_id, "message_id");
     const emoji =
       typeof args.reaction === "string" ? args.reaction : "\ud83d\udc4d";
 
-    if (messageId === undefined) {
-      return {
-        content: [
-          { type: "text", text: "message_id must be a positive integer" },
-        ],
-        isError: true,
-      };
-    }
-
-    const chat = getChatById(chatId);
-    if (!chat)
-      return {
-        content: [{ type: "text", text: "Chat not found: " + chatId }],
-        isError: true,
-      };
-
-    const client = mtprotoService.getClient();
-    const entity = chat.username ? chat.username : chat.id;
-
-    await mtprotoService.withFloodWaitHandling(async () => {
-      const inputPeer = await client.getInputEntity(entity);
-      await client.invoke(
-        new Api.messages.SendReaction({
-          peer: inputPeer,
-          msgId: messageId,
-          reaction: [new Api.ReactionEmoji({ emoticon: emoji })],
-        }),
-      );
-    });
+    const { fromCache } = await sendReactionApi(chatId, messageId, emoji);
 
     return {
       content: [
@@ -70,6 +37,7 @@ export async function sendReaction(
           text: "Reaction " + emoji + " sent to message " + messageId + ".",
         },
       ],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/setBotCommands.ts b/src/lib/mcp/telegram/tools/setBotCommands.ts
index 83e2a7be5..25ccb28a3 100644
--- a/src/lib/mcp/telegram/tools/setBotCommands.ts
+++ b/src/lib/mcp/telegram/tools/setBotCommands.ts
@@ -1,9 +1,8 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import type { BotCommandInput } from "../apiResultTypes";
+import type { BotCommandInput } from "../api/apiResultTypes";
+import { setBotCommands as setBotCommandsApi } from "../api/setBotCommands";
 
 export const tool: MCPTool = {
   name: "set_bot_commands",
@@ -24,39 +23,19 @@ export async function setBotCommands(
 ): Promise<MCPToolResult> {
   try {
     const cmds = Array.isArray(args.commands) ? args.commands : [];
-    if (cmds.length === 0)
-      return {
-        content: [{ type: "text", text: "commands array is required" }],
-        isError: true,
-      };
 
-    const client = mtprotoService.getClient();
-
-    const botCommands = cmds.map(
-      (c: BotCommandInput) =>
-        new Api.BotCommand({
-          command: String(c.command ?? ""),
-          description: String(c.description ?? ""),
-        }),
+    const { data: count, fromCache } = await setBotCommandsApi(
+      cmds as BotCommandInput[],
     );
 
-    await mtprotoService.withFloodWaitHandling(async () => {
-      await client.invoke(
-        new Api.bots.SetBotCommands({
-          scope: new Api.BotCommandScopeDefault(),
-          langCode: "",
-          commands: botCommands,
-        }),
-      );
-    });
-
     return {
       content: [
         {
           type: "text",
-          text: "Bot commands updated: " + cmds.length + " commands.",
+          text: "Bot commands updated: " + count + " commands.",
         },
       ],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/setPrivacySettings.ts b/src/lib/mcp/telegram/tools/setPrivacySettings.ts
index 98c84d94c..fb615a575 100644
--- a/src/lib/mcp/telegram/tools/setPrivacySettings.ts
+++ b/src/lib/mcp/telegram/tools/setPrivacySettings.ts
@@ -1,8 +1,7 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
+import { setPrivacySettings as setPrivacySettingsApi } from "../api/setPrivacySettings";
 
 export const tool: MCPTool = {
   name: "set_privacy_settings",
@@ -25,61 +24,7 @@ export async function setPrivacySettings(
     const keyStr = typeof args.setting === "string" ? args.setting : "";
     const ruleStr = typeof args.value === "string" ? args.value : "";
 
-    if (!keyStr)
-      return {
-        content: [{ type: "text", text: "setting is required" }],
-        isError: true,
-      };
-    if (!ruleStr)
-      return {
-        content: [{ type: "text", text: "value is required" }],
-        isError: true,
-      };
-
-    const client = mtprotoService.getClient();
-
-    const keyMap: Record<string, Api.TypeInputPrivacyKey> = {
-      phone_number: new Api.InputPrivacyKeyPhoneNumber(),
-      last_seen: new Api.InputPrivacyKeyStatusTimestamp(),
-      profile_photo: new Api.InputPrivacyKeyProfilePhoto(),
-      forwards: new Api.InputPrivacyKeyForwards(),
-      phone_call: new Api.InputPrivacyKeyPhoneCall(),
-      chat_invite: new Api.InputPrivacyKeyChatInvite(),
-    };
-
-    const key = keyMap[keyStr];
-    if (!key) {
-      return {
-        content: [{ type: "text", text: "Unknown privacy key: " + keyStr }],
-        isError: true,
-      };
-    }
-
-    const ruleMap: Record<string, Api.TypeInputPrivacyRule> = {
-      allow_all: new Api.InputPrivacyValueAllowAll(),
-      allow_contacts: new Api.InputPrivacyValueAllowContacts(),
-      disallow_all: new Api.InputPrivacyValueDisallowAll(),
-    };
-
-    const rule = ruleMap[ruleStr];
-    if (!rule) {
-      return {
-        content: [
-          {
-            type: "text",
-            text:
-              "Unknown rule: " +
-              ruleStr +
-              ". Valid: allow_all, allow_contacts, disallow_all",
-          },
-        ],
-        isError: true,
-      };
-    }
-
-    await mtprotoService.withFloodWaitHandling(async () => {
-      await client.invoke(new Api.account.SetPrivacy({ key, rules: [rule] }));
-    });
+    const { fromCache } = await setPrivacySettingsApi(keyStr, ruleStr);
 
     return {
       content: [
@@ -88,6 +33,7 @@ export async function setPrivacySettings(
           text: "Privacy setting " + keyStr + " set to " + ruleStr + ".",
         },
       ],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/setProfilePhoto.ts b/src/lib/mcp/telegram/tools/setProfilePhoto.ts
index 952a2724a..b93e9fa75 100644
--- a/src/lib/mcp/telegram/tools/setProfilePhoto.ts
+++ b/src/lib/mcp/telegram/tools/setProfilePhoto.ts
@@ -1,5 +1,7 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
+import { ErrorCategory, logAndFormatError } from "../../errorHandler";
+import { setProfilePhoto as setProfilePhotoApi } from "../api/setProfilePhoto";
 
 export const tool: MCPTool = {
   name: "set_profile_photo",
@@ -14,16 +16,26 @@ export const tool: MCPTool = {
 };
 
 export async function setProfilePhoto(
-  _args: Record<string, unknown>,
+  args: Record<string, unknown>,
   _context: TelegramMCPContext,
 ): Promise<MCPToolResult> {
-  return {
-    content: [
-      {
-        type: "text",
-        text: "set_profile_photo requires file upload which is not supported via MCP text interface. Use the Telegram client directly.",
-      },
-    ],
-    isError: true,
-  };
+  try {
+    const filePath = typeof args.file_path === "string" ? args.file_path : "";
+    await setProfilePhotoApi(filePath);
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: "This should not be reached",
+        },
+      ],
+    };
+  } catch (error) {
+    return logAndFormatError(
+      "set_profile_photo",
+      error instanceof Error ? error : new Error(String(error)),
+      ErrorCategory.PROFILE,
+    );
+  }
 }
diff --git a/src/lib/mcp/telegram/tools/subscribePublicChannel.ts b/src/lib/mcp/telegram/tools/subscribePublicChannel.ts
index 07977db98..352eb98bb 100644
--- a/src/lib/mcp/telegram/tools/subscribePublicChannel.ts
+++ b/src/lib/mcp/telegram/tools/subscribePublicChannel.ts
@@ -1,9 +1,7 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import { toInputChannel } from "../apiCastHelpers";
+import { subscribePublicChannel as subscribePublicChannelApi } from "../api/subscribePublicChannel";
 
 export const tool: MCPTool = {
   name: "subscribe_public_channel",
@@ -29,19 +27,10 @@ export async function subscribePublicChannel(
         isError: true,
       };
 
-    const client = mtprotoService.getClient();
-
-    await mtprotoService.withFloodWaitHandling(async () => {
-      const inputChannel = await client.getInputEntity(username);
-      await client.invoke(
-        new Api.channels.JoinChannel({
-          channel: toInputChannel(inputChannel),
-        }),
-      );
-    });
-
+    const { fromCache } = await subscribePublicChannelApi(username);
     return {
       content: [{ type: "text", text: `Subscribed to channel: ${username}` }],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/unarchiveChat.ts b/src/lib/mcp/telegram/tools/unarchiveChat.ts
index 7f30c4f61..e7516625d 100644
--- a/src/lib/mcp/telegram/tools/unarchiveChat.ts
+++ b/src/lib/mcp/telegram/tools/unarchiveChat.ts
@@ -2,9 +2,7 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { validateId } from "../../validation";
-import { getChatById } from "../telegramApi";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
+import { unarchiveChat as unarchiveChatApi } from "../api/unarchiveChat";
 
 export const tool: MCPTool = {
   name: "unarchive_chat",
@@ -24,32 +22,11 @@ export async function unarchiveChat(
 ): Promise<MCPToolResult> {
   try {
     const chatId = validateId(args.chat_id, "chat_id");
-
-    const chat = getChatById(chatId);
-    if (!chat)
-      return {
-        content: [{ type: "text", text: `Chat not found: ${chatId}` }],
-        isError: true,
-      };
-
-    const client = mtprotoService.getClient();
-    const entity = chat.username ? chat.username : chat.id;
-
-    await mtprotoService.withFloodWaitHandling(async () => {
-      const inputPeer = await client.getInputEntity(entity);
-      await client.invoke(
-        new Api.folders.EditPeerFolders({
-          folderPeers: [
-            new Api.InputFolderPeer({
-              peer: inputPeer,
-              folderId: 0, // 0 = Main folder (unarchive)
-            }),
-          ],
-        }),
-      );
-    });
-
-    return { content: [{ type: "text", text: `Chat ${chatId} unarchived.` }] };
+    const { fromCache } = await unarchiveChatApi(chatId);
+    return {
+      content: [{ type: "text", text: `Chat ${chatId} unarchived.` }],
+      fromCache,
+    };
   } catch (error) {
     return logAndFormatError(
       "unarchive_chat",
diff --git a/src/lib/mcp/telegram/tools/unbanUser.ts b/src/lib/mcp/telegram/tools/unbanUser.ts
index 655e85463..15366f34d 100644
--- a/src/lib/mcp/telegram/tools/unbanUser.ts
+++ b/src/lib/mcp/telegram/tools/unbanUser.ts
@@ -2,10 +2,8 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { validateId } from "../../validation";
-import { getChatById } from "../telegramApi";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import { toInputChannel, toInputPeer } from "../apiCastHelpers";
+import { unbanUser as unbanUserApi } from "../api/unbanUser";
+import { getChatById } from "../api/helpers";
 
 export const tool: MCPTool = {
   name: "unban_user",
@@ -28,45 +26,14 @@ export async function unbanUser(
     const chatId = validateId(args.chat_id, "chat_id");
     const userId = validateId(args.user_id, "user_id");
 
+    await unbanUserApi(chatId, userId);
+
     const chat = getChatById(chatId);
-    if (!chat)
-      return {
-        content: [{ type: "text", text: `Chat not found: ${chatId}` }],
-        isError: true,
-      };
-
-    if (chat.type !== "channel" && chat.type !== "supergroup") {
-      return {
-        content: [
-          {
-            type: "text",
-            text: "Unban is only available for channels/supergroups.",
-          },
-        ],
-        isError: true,
-      };
-    }
-
-    const client = mtprotoService.getClient();
-    const entity = chat.username ? chat.username : chat.id;
-
-    await mtprotoService.withFloodWaitHandling(async () => {
-      const inputChannel = await client.getInputEntity(entity);
-      const inputUser = await client.getInputEntity(userId);
-      await client.invoke(
-        new Api.channels.EditBanned({
-          channel: toInputChannel(inputChannel),
-          participant: toInputPeer(inputUser),
-          bannedRights: new Api.ChatBannedRights({ untilDate: 0 }),
-        }),
-      );
-    });
-
     return {
       content: [
         {
           type: "text",
-          text: `User ${userId} unbanned from ${chat.title ?? chatId}.`,
+          text: `User ${userId} unbanned from ${chat?.title ?? chatId}.`,
         },
       ],
     };
diff --git a/src/lib/mcp/telegram/tools/unblockUser.ts b/src/lib/mcp/telegram/tools/unblockUser.ts
index 5fc2026bb..d4f1e6cde 100644
--- a/src/lib/mcp/telegram/tools/unblockUser.ts
+++ b/src/lib/mcp/telegram/tools/unblockUser.ts
@@ -2,9 +2,7 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { validateId } from "../../validation";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
-import { toInputPeer } from "../apiCastHelpers";
+import { unblockUser as unblockUserApi } from "../api/unblockUser";
 
 export const tool: MCPTool = {
   name: "unblock_user",
@@ -24,14 +22,8 @@ export async function unblockUser(
 ): Promise<MCPToolResult> {
   try {
     const userId = validateId(args.user_id, "user_id");
-    const client = mtprotoService.getClient();
 
-    await mtprotoService.withFloodWaitHandling(async () => {
-      const inputUser = await client.getInputEntity(userId);
-      await client.invoke(
-        new Api.contacts.Unblock({ id: toInputPeer(inputUser) }),
-      );
-    });
+    await unblockUserApi(userId);
 
     return { content: [{ type: "text", text: `User ${userId} unblocked.` }] };
   } catch (error) {
diff --git a/src/lib/mcp/telegram/tools/unmuteChat.ts b/src/lib/mcp/telegram/tools/unmuteChat.ts
index 545a6a6de..fb1bc70dc 100644
--- a/src/lib/mcp/telegram/tools/unmuteChat.ts
+++ b/src/lib/mcp/telegram/tools/unmuteChat.ts
@@ -2,9 +2,7 @@ import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
 import { validateId } from "../../validation";
-import { getChatById } from "../telegramApi";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
+import { unmuteChat as unmuteChatApi } from "../api/unmuteChat";
 
 export const tool: MCPTool = {
   name: "unmute_chat",
@@ -24,30 +22,11 @@ export async function unmuteChat(
 ): Promise<MCPToolResult> {
   try {
     const chatId = validateId(args.chat_id, "chat_id");
-
-    const chat = getChatById(chatId);
-    if (!chat)
-      return {
-        content: [{ type: "text", text: `Chat not found: ${chatId}` }],
-        isError: true,
-      };
-
-    const client = mtprotoService.getClient();
-    const entity = chat.username ? chat.username : chat.id;
-
-    await mtprotoService.withFloodWaitHandling(async () => {
-      const inputPeer = await client.getInputEntity(entity);
-      await client.invoke(
-        new Api.account.UpdateNotifySettings({
-          peer: new Api.InputNotifyPeer({ peer: inputPeer }),
-          settings: new Api.InputPeerNotifySettings({
-            muteUntil: 0,
-          }),
-        }),
-      );
-    });
-
-    return { content: [{ type: "text", text: `Chat ${chatId} unmuted.` }] };
+    const { fromCache } = await unmuteChatApi(chatId);
+    return {
+      content: [{ type: "text", text: `Chat ${chatId} unmuted.` }],
+      fromCache,
+    };
   } catch (error) {
     return logAndFormatError(
       "unmute_chat",
diff --git a/src/lib/mcp/telegram/tools/unpinMessage.ts b/src/lib/mcp/telegram/tools/unpinMessage.ts
index cc0a3c49a..960e58e95 100644
--- a/src/lib/mcp/telegram/tools/unpinMessage.ts
+++ b/src/lib/mcp/telegram/tools/unpinMessage.ts
@@ -1,10 +1,8 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { getChatById } from "../telegramApi";
-import { validateId } from "../../validation";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
+import { validateId, validatePositiveInt } from "../../validation";
+import { unpinMessage as unpinMessageApi } from "../api/unpinMessage";
 
 export const tool: MCPTool = {
   name: "unpin_message",
@@ -25,41 +23,9 @@ export async function unpinMessage(
 ): Promise<MCPToolResult> {
   try {
     const chatId = validateId(args.chat_id, "chat_id");
-    const messageId =
-      typeof args.message_id === "number" && Number.isInteger(args.message_id)
-        ? args.message_id
-        : undefined;
+    const messageId = validatePositiveInt(args.message_id, "message_id");
 
-    if (messageId === undefined) {
-      return {
-        content: [
-          { type: "text", text: "message_id must be a positive integer" },
-        ],
-        isError: true,
-      };
-    }
-
-    const chat = getChatById(chatId);
-    if (!chat) {
-      return {
-        content: [{ type: "text", text: `Chat not found: ${chatId}` }],
-        isError: true,
-      };
-    }
-
-    const entity = chat.username ? chat.username : chat.id;
-    const client = mtprotoService.getClient();
-
-    await mtprotoService.withFloodWaitHandling(async () => {
-      const inputPeer = await client.getInputEntity(entity);
-      await client.invoke(
-        new Api.messages.UpdatePinnedMessage({
-          peer: inputPeer,
-          id: messageId,
-          unpin: true,
-        }),
-      );
-    });
+    const { fromCache } = await unpinMessageApi(chatId, messageId);
 
     return {
       content: [
@@ -68,6 +34,7 @@ export async function unpinMessage(
           text: `Message ${messageId} unpinned in chat ${chatId}.`,
         },
       ],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/telegram/tools/updateProfile.ts b/src/lib/mcp/telegram/tools/updateProfile.ts
index b4d2f4c3e..7b2d774a8 100644
--- a/src/lib/mcp/telegram/tools/updateProfile.ts
+++ b/src/lib/mcp/telegram/tools/updateProfile.ts
@@ -1,9 +1,8 @@
 import type { MCPTool, MCPToolResult } from "../../types";
 import type { TelegramMCPContext } from "../types";
 import { ErrorCategory, logAndFormatError } from "../../errorHandler";
-import { mtprotoService } from "../../../../services/mtprotoService";
-import { Api } from "telegram";
 import { optString } from "../args";
+import { updateProfile as updateProfileApi } from "../api/updateProfile";
 
 export const tool: MCPTool = {
   name: "update_profile",
@@ -27,39 +26,17 @@ export async function updateProfile(
     const lastName = optString(args, "last_name");
     const about = optString(args, "about");
 
-    if (!firstName && !lastName && !about) {
-      return {
-        content: [
-          {
-            type: "text",
-            text: "At least one of first_name, last_name, or about is required.",
-          },
-        ],
-        isError: true,
-      };
-    }
-
-    const client = mtprotoService.getClient();
-
-    await mtprotoService.withFloodWaitHandling(async () => {
-      await client.invoke(
-        new Api.account.UpdateProfile({
-          firstName: firstName ?? undefined,
-          lastName: lastName ?? undefined,
-          about: about ?? undefined,
-        }),
-      );
+    const { data: updates, fromCache } = await updateProfileApi({
+      firstName,
+      lastName,
+      about,
     });
 
-    const updates: string[] = [];
-    if (firstName) updates.push("first_name: " + firstName);
-    if (lastName) updates.push("last_name: " + lastName);
-    if (about) updates.push("about: " + about);
-
     return {
       content: [
         { type: "text", text: "Profile updated: " + updates.join(", ") },
       ],
+      fromCache,
     };
   } catch (error) {
     return logAndFormatError(
diff --git a/src/lib/mcp/types.ts b/src/lib/mcp/types.ts
index 5dfaf0b3a..207562efb 100644
--- a/src/lib/mcp/types.ts
+++ b/src/lib/mcp/types.ts
@@ -31,6 +31,7 @@ export interface MCPToolResult {
     text: string;
   }>;
   isError?: boolean;
+  fromCache?: boolean;
 }
 
 export interface MCPRequest {
diff --git a/src/lib/mcp/validation.test.ts b/src/lib/mcp/validation.test.ts
new file mode 100644
index 000000000..583740c77
--- /dev/null
+++ b/src/lib/mcp/validation.test.ts
@@ -0,0 +1,283 @@
+import { describe, it, expect } from "vitest";
+import {
+  ValidationError,
+  validateId,
+  validateIdList,
+  validatePositiveInt,
+  validateOptionalId,
+} from "./validation";
+
+describe("ValidationError", () => {
+  it("should have correct name property", () => {
+    const error = new ValidationError("test message");
+    expect(error.name).toBe("ValidationError");
+    expect(error.message).toBe("test message");
+  });
+});
+
+describe("validateId", () => {
+  describe("valid inputs", () => {
+    it("should accept valid positive integer", () => {
+      expect(validateId(12345, "chat_id")).toBe(12345);
+    });
+
+    it("should accept valid negative integer", () => {
+      expect(validateId(-100123456789, "chat_id")).toBe(-100123456789);
+    });
+
+    it("should accept zero", () => {
+      expect(validateId(0, "user_id")).toBe(0);
+    });
+
+    it("should accept string integer", () => {
+      expect(validateId("67890", "chat_id")).toBe(67890);
+    });
+
+    it("should accept negative string integer", () => {
+      expect(validateId("-123456", "chat_id")).toBe(-123456);
+    });
+
+    it("should accept username with @ prefix", () => {
+      expect(validateId("@username", "username")).toBe("@username");
+    });
+
+    it("should accept username without @ and add prefix", () => {
+      expect(validateId("username", "username")).toBe("@username");
+    });
+
+    it("should accept username with underscores", () => {
+      expect(validateId("user_name_123", "username")).toBe("@user_name_123");
+    });
+
+    it("should accept 5-character username", () => {
+      expect(validateId("abcde", "username")).toBe("@abcde");
+    });
+  });
+
+  describe("invalid inputs", () => {
+    it("should throw for username shorter than 5 characters", () => {
+      expect(() => validateId("abcd", "username")).toThrow(ValidationError);
+      expect(() => validateId("abcd", "username")).toThrow(
+        "Invalid username: 'abcd'. Must be a valid integer ID or a username string."
+      );
+    });
+
+    it("should throw for username with special characters", () => {
+      expect(() => validateId("user@name", "username")).toThrow(ValidationError);
+    });
+
+    it("should throw for username with spaces", () => {
+      expect(() => validateId("user name", "username")).toThrow(ValidationError);
+    });
+
+    it("should throw for non-string non-number", () => {
+      expect(() => validateId({}, "chat_id")).toThrow(ValidationError);
+      expect(() => validateId({}, "chat_id")).toThrow(
+        "Type must be an integer or a string"
+      );
+    });
+
+    it("should throw for null", () => {
+      expect(() => validateId(null, "chat_id")).toThrow(ValidationError);
+    });
+
+    it("should throw for boolean", () => {
+      expect(() => validateId(true, "chat_id")).toThrow(ValidationError);
+    });
+
+    it("should throw for float number", () => {
+      expect(() => validateId(123.45, "chat_id")).toThrow(ValidationError);
+      expect(() => validateId(123.45, "chat_id")).toThrow(
+        "ID is out of the valid integer range"
+      );
+    });
+
+    it("should throw for NaN string", () => {
+      // "abc" is too short to be a valid username (< 5 chars) and is not a number
+      expect(() => validateId("abc", "chat_id")).toThrow(
+        ValidationError
+      );
+      expect(() => validateId("abc", "chat_id")).toThrow(
+        "Must be a valid integer ID or a username string"
+      );
+    });
+
+    it("should throw for empty string", () => {
+      expect(() => validateId("", "chat_id")).toThrow(ValidationError);
+    });
+
+    // Note: JavaScript cannot accurately represent integers beyond Number.MAX_SAFE_INTEGER
+    // (2^53 - 1 = 9007199254740991), so testing for 2^63 range checks is not possible
+    // with native JavaScript numbers. The validateId function uses 2^63 bounds which
+    // are beyond JS precision, so these checks effectively never trigger for JS number inputs.
+    // We skip these tests as they test impossible conditions in JavaScript.
+    it.skip("should throw for integer out of range (too large)", () => {
+      const tooLarge = 2 ** 63;
+      expect(() => validateId(tooLarge, "chat_id")).toThrow(ValidationError);
+      expect(() => validateId(tooLarge, "chat_id")).toThrow(
+        "ID is out of the valid integer range"
+      );
+    });
+
+    it.skip("should throw for integer out of range (too small)", () => {
+      const tooSmall = -(2 ** 63) - 1;
+      expect(() => validateId(tooSmall, "chat_id")).toThrow(ValidationError);
+    });
+
+    it.skip("should throw for string integer out of range", () => {
+      expect(() => validateId("9223372036854775808", "chat_id")).toThrow(
+        ValidationError
+      );
+    });
+  });
+});
+
+describe("validateIdList", () => {
+  it("should accept valid array of integers", () => {
+    const result = validateIdList([123, 456, 789], "user_ids");
+    expect(result).toEqual([123, 456, 789]);
+  });
+
+  it("should accept valid array of strings", () => {
+    const result = validateIdList(["123", "456"], "chat_ids");
+    expect(result).toEqual([123, 456]);
+  });
+
+  it("should accept valid array of usernames", () => {
+    const result = validateIdList(["@alice", "bobbb"], "usernames");
+    expect(result).toEqual(["@alice", "@bobbb"]);
+  });
+
+  it("should accept mixed valid IDs", () => {
+    const result = validateIdList([123, "@username", "456"], "ids");
+    expect(result).toEqual([123, "@username", 456]);
+  });
+
+  it("should accept empty array", () => {
+    const result = validateIdList([], "ids");
+    expect(result).toEqual([]);
+  });
+
+  it("should throw for non-array", () => {
+    expect(() => validateIdList("not_array", "ids")).toThrow(ValidationError);
+    expect(() => validateIdList("not_array", "ids")).toThrow(
+      "Invalid ids: must be an array of IDs"
+    );
+  });
+
+  it("should throw for array with invalid element", () => {
+    expect(() => validateIdList([123, null, 456], "ids")).toThrow(
+      ValidationError
+    );
+  });
+
+  it("should throw with correct parameter name for invalid element", () => {
+    expect(() => validateIdList([123, "bad"], "user_ids")).toThrow(
+      "Invalid user_ids[1]"
+    );
+  });
+
+  it("should throw for array with short username", () => {
+    expect(() => validateIdList(["@alice", "bob"], "usernames")).toThrow(
+      ValidationError
+    );
+  });
+});
+
+describe("validatePositiveInt", () => {
+  describe("valid inputs", () => {
+    it("should accept positive number", () => {
+      expect(validatePositiveInt(42, "message_id")).toBe(42);
+    });
+
+    it("should accept positive string", () => {
+      expect(validatePositiveInt("123", "limit")).toBe(123);
+    });
+
+    it("should accept large positive integer", () => {
+      expect(validatePositiveInt(999999999, "count")).toBe(999999999);
+    });
+  });
+
+  describe("invalid inputs", () => {
+    it("should throw for zero", () => {
+      expect(() => validatePositiveInt(0, "limit")).toThrow(ValidationError);
+      expect(() => validatePositiveInt(0, "limit")).toThrow(
+        "Must be a positive integer"
+      );
+    });
+
+    it("should throw for negative number", () => {
+      expect(() => validatePositiveInt(-5, "count")).toThrow(ValidationError);
+    });
+
+    it("should throw for negative string", () => {
+      expect(() => validatePositiveInt("-10", "offset")).toThrow(
+        ValidationError
+      );
+    });
+
+    it("should throw for float number", () => {
+      expect(() => validatePositiveInt(3.14, "limit")).toThrow(ValidationError);
+    });
+
+    it("should throw for non-number string", () => {
+      expect(() => validatePositiveInt("abc", "count")).toThrow(
+        ValidationError
+      );
+    });
+
+    it("should throw for non-number non-string", () => {
+      expect(() => validatePositiveInt({}, "limit")).toThrow(ValidationError);
+      expect(() => validatePositiveInt({}, "limit")).toThrow(
+        "Must be a positive integer"
+      );
+    });
+
+    it("should throw for null", () => {
+      expect(() => validatePositiveInt(null, "count")).toThrow(ValidationError);
+    });
+
+    it("should throw for boolean", () => {
+      expect(() => validatePositiveInt(true, "limit")).toThrow(ValidationError);
+    });
+
+    it("should throw for empty string", () => {
+      expect(() => validatePositiveInt("", "offset")).toThrow(ValidationError);
+    });
+
+    it("should throw for zero string", () => {
+      expect(() => validatePositiveInt("0", "limit")).toThrow(ValidationError);
+    });
+  });
+});
+
+describe("validateOptionalId", () => {
+  it("should return undefined for undefined", () => {
+    expect(validateOptionalId(undefined, "reply_to")).toBeUndefined();
+  });
+
+  it("should return undefined for null", () => {
+    expect(validateOptionalId(null, "reply_to")).toBeUndefined();
+  });
+
+  it("should delegate to validateId for valid integer", () => {
+    expect(validateOptionalId(12345, "chat_id")).toBe(12345);
+  });
+
+  it("should delegate to validateId for valid string", () => {
+    expect(validateOptionalId("67890", "user_id")).toBe(67890);
+  });
+
+  it("should delegate to validateId for valid username", () => {
+    expect(validateOptionalId("username", "username")).toBe("@username");
+  });
+
+  it("should throw for invalid value", () => {
+    expect(() => validateOptionalId("bad", "chat_id")).toThrow(ValidationError);
+  });
+
+  it("should throw for invalid type", () => {
+    expect(() => validateOptionalId({}, "user_id")).toThrow(ValidationError);
+  });
+});
diff --git a/src/lib/mcp/validation.ts b/src/lib/mcp/validation.ts
index 4b0cb8a50..9d0e75f49 100644
--- a/src/lib/mcp/validation.ts
+++ b/src/lib/mcp/validation.ts
@@ -72,6 +72,37 @@ export function validateIdList(
   });
 }
 
+/**
+ * Validate a positive integer parameter (e.g. message IDs)
+ */
+export function validatePositiveInt(
+  value: unknown,
+  paramName: string,
+): number {
+  if (typeof value === "number") {
+    if (!Number.isInteger(value) || value <= 0) {
+      throw new ValidationError(
+        `Invalid ${paramName}: ${value}. Must be a positive integer.`,
+      );
+    }
+    return value;
+  }
+
+  if (typeof value === "string") {
+    const intValue = Number.parseInt(value, 10);
+    if (Number.isNaN(intValue) || intValue <= 0) {
+      throw new ValidationError(
+        `Invalid ${paramName}: '${value}'. Must be a positive integer.`,
+      );
+    }
+    return intValue;
+  }
+
+  throw new ValidationError(
+    `Invalid ${paramName}: ${String(value)}. Must be a positive integer.`,
+  );
+}
+
 /**
  * Validate optional ID (can be undefined)
  */
diff --git a/src/providers/TelegramProvider.tsx b/src/providers/TelegramProvider.tsx
index c856f3b47..5be0dacca 100644
--- a/src/providers/TelegramProvider.tsx
+++ b/src/providers/TelegramProvider.tsx
@@ -16,6 +16,7 @@ import {
 } from "../store/telegramSelectors";
 import { initializeTelegram, connectTelegram } from "../store/telegram";
 import { mtprotoService } from "../services/mtprotoService";
+import { telegramSyncService } from "../services/telegram";
 
 interface TelegramContextType {
   isAuthenticated: boolean;
@@ -180,6 +181,34 @@ const TelegramProvider = ({ children }: TelegramProviderProps) => {
     checkConnection();
   }, [shouldSetupTelegram, isInitialized, connectionStatus, userId]);
 
+  // Start sync when connected and authenticated
+  useEffect(() => {
+    if (
+      !shouldSetupTelegram ||
+      !isInitialized ||
+      connectionStatus !== "connected" ||
+      !(isAuthenticated || hasSession) ||
+      !userId
+    ) {
+      return;
+    }
+
+    if (!mtprotoService.isReady()) return;
+
+    telegramSyncService.startSync(userId);
+
+    return () => {
+      telegramSyncService.stopSync();
+    };
+  }, [
+    shouldSetupTelegram,
+    isInitialized,
+    connectionStatus,
+    isAuthenticated,
+    hasSession,
+    userId,
+  ]);
+
   const checkConnection = async (): Promise<boolean> => {
     try {
       return await mtprotoService.checkConnection(userId || undefined);
diff --git a/src/services/api/authApi.ts b/src/services/api/authApi.ts
index b17cf2afe..a05c918cd 100644
--- a/src/services/api/authApi.ts
+++ b/src/services/api/authApi.ts
@@ -15,6 +15,7 @@ export async function consumeLoginToken(loginToken: string): Promise<string> {
     undefined,
     { requireAuth: false },
   );
+  console.log("[ConsumeLoginToken] Response", response);
   if (!response.success || !response.data?.jwtToken) {
     throw new Error("Login token invalid or expired");
   }
diff --git a/src/services/messageLoader.ts b/src/services/messageLoader.ts
index 0dadcd1b5..779e7173f 100644
--- a/src/services/messageLoader.ts
+++ b/src/services/messageLoader.ts
@@ -1,13 +1,12 @@
 /**
  * Smart Message Loading Service
  *
- * Implements Telegram-TT–style message fetching with:
+ * Implements message fetching with:
  * - Three-direction loading (Around, Backward, Forward)
  * - AbortController per chat/thread for request cancellation
  * - Batch ID fetching (up to 100 IDs per request)
  * - Budget preloading (two-pass: viewport first, buffer second)
  *
- * Reference: Telegram-TT's src/global/actions/api/messages.ts
  */
 
 import { Api } from "telegram/tl";
@@ -80,10 +79,7 @@ function getAbortKey(chatId: string, threadId?: string): string {
  * Cancel any in-flight message fetch for this chat/thread.
  * Call when user switches chats to prevent stale data.
  */
-export function cancelMessageFetch(
-  chatId: string,
-  threadId?: string,
-): void {
+export function cancelMessageFetch(chatId: string, threadId?: string): void {
   const key = getAbortKey(chatId, threadId);
   const existing = abortControllers.get(key);
   if (existing) {
@@ -237,7 +233,10 @@ export async function loadMessages(
     return messages;
   } catch (error) {
     if (controller.signal.aborted) return [];
-    console.error(`[MessageLoader] Failed to load messages for ${chatId}:`, error);
+    console.error(
+      `[MessageLoader] Failed to load messages for ${chatId}:`,
+      error,
+    );
     throw error;
   }
 }
@@ -310,9 +309,7 @@ export async function fetchMessagesByIds(
   // Process in batches of BATCH_FETCH_LIMIT
   for (let i = 0; i < messageIds.length; i += BATCH_FETCH_LIMIT) {
     const batch = messageIds.slice(i, i + BATCH_FETCH_LIMIT);
-    const inputIds = batch.map(
-      (id) => new Api.InputMessageID({ id }),
-    );
+    const inputIds = batch.map((id) => new Api.InputMessageID({ id }));
 
     try {
       const result = await mtprotoService.withFloodWaitHandling(async () => {
@@ -335,7 +332,9 @@ export async function fetchMessagesByIds(
       allMessages.push(...messages);
     } catch (error) {
       console.error(
-        `[MessageLoader] Batch fetch failed for ${chatId} (batch ${i / BATCH_FETCH_LIMIT}):`,
+        `[MessageLoader] Batch fetch failed for ${chatId} (batch ${
+          i / BATCH_FETCH_LIMIT
+        }):`,
         error,
       );
     }
@@ -417,7 +416,8 @@ function convertApiMessages(result: any, chatId: string): TelegramMessage[] {
     // Media
     if (msg.media && typeof msg.media === "object") {
       const media = msg.media as Record<string, unknown>;
-      const className = (media.constructor as { className?: string })?.className;
+      const className = (media.constructor as { className?: string })
+        ?.className;
       telegramMsg.media = {
         type: className ?? "unknown",
       };
diff --git a/src/services/telegram/entityBuilders.ts b/src/services/telegram/entityBuilders.ts
new file mode 100644
index 000000000..f0700dbb2
--- /dev/null
+++ b/src/services/telegram/entityBuilders.ts
@@ -0,0 +1,230 @@
+/**
+ * Entity builders — convert raw GramJS objects to Redux-compatible types.
+ */
+
+import type {
+  TelegramChat,
+  TelegramMessage,
+  TelegramUser,
+} from "../../store/telegram/types";
+
+// ---------------------------------------------------------------------------
+// Peer ID helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a GramJS peer object to a string ID.
+ * Handles PeerUser, PeerChat, PeerChannel, and InputPeer* variants.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function buildPeerId(peer: any): string {
+  if (!peer || typeof peer !== "object") return "";
+  if (peer.userId != null) return String(peer.userId);
+  if (peer.chatId != null) return String(peer.chatId);
+  if (peer.channelId != null) return String(peer.channelId);
+  return "";
+}
+
+/**
+ * Determine chat type from a GramJS entity object.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function getChatType(entity: any): TelegramChat["type"] {
+  if (!entity) return "private";
+  const className: string = entity.className ?? "";
+  if (className === "Channel") {
+    return entity.megagroup ? "supergroup" : "channel";
+  }
+  if (className === "Chat" || className === "ChatForbidden") {
+    return "group";
+  }
+  return "private";
+}
+
+// ---------------------------------------------------------------------------
+// Chat builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a TelegramChat from a GramJS dialog + its peer entity.
+ *
+ * @param dialog - Raw GramJS Dialog object (has peer, unreadCount, pinned, etc.)
+ * @param entity - The resolved entity (User / Chat / Channel) for this dialog
+ * @param lastMsg - Optional last message already converted
+ */
+export function buildChat(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  dialog: any,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  entity: any,
+  lastMsg?: TelegramMessage,
+): TelegramChat {
+  const id = buildPeerId(dialog.peer ?? entity);
+  const type = getChatType(entity);
+
+  const chat: TelegramChat = {
+    id,
+    type,
+    unreadCount: dialog.unreadCount ?? 0,
+    isPinned: Boolean(dialog.pinned),
+  };
+
+  // Title
+  if (type === "private") {
+    const firstName: string = entity?.firstName ?? "";
+    const lastName: string = entity?.lastName ?? "";
+    chat.title = [firstName, lastName].filter(Boolean).join(" ") || `User ${id}`;
+  } else {
+    chat.title = entity?.title ?? `Chat ${id}`;
+  }
+
+  // Username
+  if (entity?.username) chat.username = entity.username;
+
+  // Access hash
+  if (entity?.accessHash != null) {
+    chat.accessHash = String(entity.accessHash);
+  }
+
+  // Photo
+  if (entity?.photo && entity.photo.className !== "ChatPhotoEmpty") {
+    chat.photo = {
+      smallFileId: entity.photo.photoId
+        ? String(entity.photo.photoId)
+        : undefined,
+    };
+  }
+
+  // Participants count
+  if (entity?.participantsCount != null) {
+    chat.participantsCount = entity.participantsCount;
+  }
+
+  // Last message
+  if (lastMsg) {
+    chat.lastMessage = lastMsg;
+    chat.lastMessageDate = lastMsg.date;
+  }
+
+  return chat;
+}
+
+// ---------------------------------------------------------------------------
+// Message builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a TelegramMessage from a raw GramJS message object.
+ * Compatible with both Api.Message and the raw objects from GetDialogs/GetHistory.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function buildMessage(msg: any, fallbackChatId?: string): TelegramMessage | null {
+  if (!msg || typeof msg !== "object") return null;
+
+  const id = msg.id;
+  if (id === undefined || id === null) return null;
+
+  // Determine chat ID from peerId or fallback
+  let chatId = fallbackChatId ?? "";
+  if (msg.peerId) {
+    chatId = buildPeerId(msg.peerId) || chatId;
+  }
+
+  const telegramMsg: TelegramMessage = {
+    id: String(id),
+    chatId,
+    date: typeof msg.date === "number" ? msg.date : 0,
+    message: typeof msg.message === "string" ? msg.message : "",
+    isOutgoing: Boolean(msg.out),
+    isEdited: Boolean(msg.editDate),
+    isForwarded: Boolean(msg.fwdFrom),
+  };
+
+  // From ID
+  if (msg.fromId && typeof msg.fromId === "object") {
+    telegramMsg.fromId = buildPeerId(msg.fromId);
+  }
+
+  // Reply
+  if (msg.replyTo && typeof msg.replyTo === "object") {
+    if (msg.replyTo.replyToMsgId) {
+      telegramMsg.replyToMessageId = String(msg.replyTo.replyToMsgId);
+    }
+    if (msg.replyTo.replyToTopId) {
+      telegramMsg.threadId = String(msg.replyTo.replyToTopId);
+    }
+  }
+
+  // Media
+  if (msg.media && typeof msg.media === "object") {
+    const className = (msg.media.constructor as { className?: string })?.className;
+    telegramMsg.media = { type: className ?? "unknown" };
+  }
+
+  // Views
+  if (typeof msg.views === "number") {
+    telegramMsg.views = msg.views;
+  }
+
+  return telegramMsg;
+}
+
+// ---------------------------------------------------------------------------
+// User builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a TelegramUser from a raw GramJS User object.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function buildUser(user: any): TelegramUser | null {
+  if (!user || typeof user !== "object") return null;
+  if (user.id === undefined || user.id === null) return null;
+
+  return {
+    id: String(user.id),
+    firstName: user.firstName ?? "",
+    lastName: user.lastName ?? undefined,
+    username: user.username ?? undefined,
+    phoneNumber: user.phone ?? undefined,
+    isBot: Boolean(user.bot),
+    isVerified: user.verified ? true : undefined,
+    isPremium: user.premium ? true : undefined,
+    accessHash: user.accessHash != null ? String(user.accessHash) : undefined,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Entity map builder (from GetDialogs response)
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a map of entities (users + chats/channels) indexed by their ID.
+ * GramJS returns separate `users` and `chats` arrays — this merges them.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function buildEntityMap(result: any): Map<string, any> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const map = new Map<string, any>();
+
+  const users: unknown[] = result?.users ?? [];
+  const chats: unknown[] = result?.chats ?? [];
+
+  for (const u of users) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const user = u as any;
+    if (user?.id != null) {
+      map.set(String(user.id), user);
+    }
+  }
+
+  for (const c of chats) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const chat = c as any;
+    if (chat?.id != null) {
+      map.set(String(chat.id), chat);
+    }
+  }
+
+  return map;
+}
diff --git a/src/services/telegram/index.ts b/src/services/telegram/index.ts
new file mode 100644
index 000000000..628795c53
--- /dev/null
+++ b/src/services/telegram/index.ts
@@ -0,0 +1 @@
+export { telegramSyncService } from "./syncService";
diff --git a/src/services/telegram/schedulers.ts b/src/services/telegram/schedulers.ts
new file mode 100644
index 000000000..170490642
--- /dev/null
+++ b/src/services/telegram/schedulers.ts
@@ -0,0 +1,64 @@
+/**
+ * Scheduling utilities
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyFunction = (...args: any[]) => any;
+
+export function throttle<F extends AnyFunction>(
+  fn: F,
+  ms: number,
+  shouldRunFirst = true,
+): F {
+  let waiting = false;
+  let pendingArgs: Parameters<F> | null = null;
+
+  return ((...args: Parameters<F>) => {
+    if (waiting) {
+      pendingArgs = args;
+      return;
+    }
+
+    if (shouldRunFirst) {
+      fn(...args);
+    } else {
+      pendingArgs = args;
+    }
+
+    waiting = true;
+    setTimeout(() => {
+      waiting = false;
+      if (pendingArgs) {
+        fn(...pendingArgs);
+        pendingArgs = null;
+      }
+    }, ms);
+  }) as unknown as F;
+}
+
+export function debounce<F extends AnyFunction>(
+  fn: F,
+  ms: number,
+  shouldRunFirst = false,
+  shouldRunLast = true,
+): F {
+  let waitingTimeout: ReturnType<typeof setTimeout> | null = null;
+
+  return ((...args: Parameters<F>) => {
+    if (waitingTimeout) {
+      clearTimeout(waitingTimeout);
+    } else if (shouldRunFirst) {
+      fn(...args);
+    }
+
+    waitingTimeout = setTimeout(() => {
+      if (shouldRunLast) {
+        fn(...args);
+      }
+      waitingTimeout = null;
+    }, ms);
+  }) as unknown as F;
+}
+
+export const pause = (ms: number): Promise<void> =>
+  new Promise<void>((resolve) => setTimeout(resolve, ms));
diff --git a/src/services/telegram/syncService.ts b/src/services/telegram/syncService.ts
new file mode 100644
index 000000000..47933127c
--- /dev/null
+++ b/src/services/telegram/syncService.ts
@@ -0,0 +1,554 @@
+/**
+ * Telegram Sync Service
+ *
+ * Loads all chats via GetDialogs in 100-chat batches, preloads messages for
+ * the top 20 chats, and registers real-time update handling.
+ *
+ * Coexists independently with the existing MCP tool system.
+ */
+
+import { Api } from "telegram/tl";
+import { Raw } from "telegram/events";
+import bigInt from "big-integer";
+import { mtprotoService } from "../mtprotoService";
+import { updateManager } from "../updateManager";
+import { store } from "../../store";
+import {
+  setSyncStatus,
+  replaceChats,
+  addChats,
+  setUsers,
+  addUsers,
+  addChatMessagesById,
+  setCommonBoxState,
+  setChannelPts,
+} from "../../store/telegram";
+import type { TelegramChat, TelegramUser } from "../../store/telegram/types";
+import {
+  buildChat,
+  buildMessage,
+  buildUser,
+  buildEntityMap,
+  buildPeerId,
+} from "./entityBuilders";
+import { handleUpdate } from "./updateHandler";
+import { pause } from "./schedulers";
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+const CHAT_LIST_LOAD_SLICE = 100;
+const TOP_CHAT_MESSAGES_PRELOAD_LIMIT = 20;
+const TOP_CHAT_MESSAGES_PRELOAD_INTERVAL = 100; // ms between each preload
+const MESSAGE_LIST_SLICE_DESKTOP = 60;
+const MESSAGE_LIST_SLICE_MOBILE = 40;
+const SYNC_SAFETY_TIMEOUT = 15_000; // 15s safety timeout
+const INFINITE_LOOP_MARKER = 100; // max iterations for chat loading
+
+const LOG_PREFIX = "[TelegramSync]";
+
+function getMessageSlice(): number {
+  return typeof window !== "undefined" && window.innerWidth < 768
+    ? MESSAGE_LIST_SLICE_MOBILE
+    : MESSAGE_LIST_SLICE_DESKTOP;
+}
+
+// ---------------------------------------------------------------------------
+// Sync Service
+// ---------------------------------------------------------------------------
+
+class TelegramSyncService {
+  private isSyncing = false;
+  private isSynced = false;
+  private userId: string | null = null;
+  private safetyTimeout: ReturnType<typeof setTimeout> | undefined;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private boundProcessUpdate: ((update: any) => void) | null = null;
+
+  /**
+   * Start the full sync flow:
+   * 1. Get update state (pts/seq/qts/date)
+   * 2. Register real-time update handler
+   * 3. Load all active chats (100 per batch)
+   * 4. After first batch: load messages for open chat + mark UI ready
+   * 5. Background: load archived chats + preload top 20 chat messages
+   */
+  async startSync(userId: string): Promise<void> {
+    if (this.isSyncing) {
+      console.log(LOG_PREFIX, "Sync already in progress, skipping");
+      return;
+    }
+    if (this.isSynced && this.userId === userId) {
+      console.log(LOG_PREFIX, "Already synced for this user, skipping");
+      return;
+    }
+
+    console.log(LOG_PREFIX, "Starting sync for user", userId);
+    this.userId = userId;
+    this.isSyncing = true;
+    this.isSynced = false;
+
+    store.dispatch(setSyncStatus({ userId, isSyncing: true, isSynced: false }));
+
+    // Safety timeout: release isSyncing if stuck
+    this.safetyTimeout = setTimeout(() => {
+      if (this.isSyncing) {
+        console.warn(
+          LOG_PREFIX,
+          "Safety timeout reached — releasing sync lock",
+        );
+        this.isSyncing = false;
+        store.dispatch(setSyncStatus({ userId, isSyncing: false }));
+      }
+    }, SYNC_SAFETY_TIMEOUT);
+
+    try {
+      // 1. Initialize update state + register handler
+      await this.initUpdateManager();
+
+      // 2. Load all active chats
+      await this.loadAllChats("active", async () => {
+        // After first batch callback:
+        // Load messages for currently open chat
+        await this.loadAndReplaceMessages();
+
+        // Mark sync as complete for UI
+        this.isSyncing = false;
+        this.isSynced = true;
+        clearTimeout(this.safetyTimeout);
+        store.dispatch(
+          setSyncStatus({ userId, isSyncing: false, isSynced: true }),
+        );
+        console.log(LOG_PREFIX, "Initial sync complete — UI ready");
+
+        // Background tasks (non-blocking)
+        this.loadAllChats("archived").catch((e) =>
+          console.warn(LOG_PREFIX, "Archived chat load failed:", e),
+        );
+        this.preloadTopChatMessages().catch((e) =>
+          console.warn(LOG_PREFIX, "Top chat preload failed:", e),
+        );
+      });
+    } catch (error) {
+      console.error(LOG_PREFIX, "Sync failed:", error);
+      this.isSyncing = false;
+      clearTimeout(this.safetyTimeout);
+      store.dispatch(setSyncStatus({ userId, isSyncing: false }));
+    }
+  }
+
+  /**
+   * Stop sync and clean up resources.
+   */
+  stopSync(): void {
+    console.log(LOG_PREFIX, "Stopping sync");
+    clearTimeout(this.safetyTimeout);
+
+    // Remove update handler from client
+    if (this.boundProcessUpdate) {
+      try {
+        mtprotoService
+          .getClient()
+          .removeEventHandler(this.boundProcessUpdate, new Raw({}));
+      } catch {
+        // Client may not be available
+      }
+      this.boundProcessUpdate = null;
+    }
+
+    updateManager.destroy();
+    this.isSyncing = false;
+    this.isSynced = false;
+    this.userId = null;
+  }
+
+  // -------------------------------------------------------------------------
+  // Update Manager initialization
+  // -------------------------------------------------------------------------
+
+  private async initUpdateManager(): Promise<void> {
+    const client = mtprotoService.getClient();
+    const userId = this.userId!;
+
+    // Fetch current update state from Telegram
+    const state = await mtprotoService.invoke<Api.updates.State>(
+      new Api.updates.GetState(),
+    );
+
+    const commonBoxState = {
+      seq: state.seq,
+      date: state.date,
+      pts: state.pts,
+      qts: state.qts,
+    };
+
+    console.log(LOG_PREFIX, "Update state:", commonBoxState);
+
+    // Store in Redux
+    store.dispatch(setCommonBoxState({ userId, commonBoxState }));
+
+    // Initialize the update manager with client + handler
+    updateManager.init(client, (update, source) => {
+      handleUpdate(update, userId, source);
+    });
+    updateManager.setInitialState(commonBoxState);
+
+    // Register GramJS event handler
+    this.boundProcessUpdate = (update) => {
+      updateManager.processUpdate(update);
+    };
+    client.addEventHandler(this.boundProcessUpdate);
+
+    console.log(
+      LOG_PREFIX,
+      "Update manager initialized, event handler registered",
+    );
+  }
+
+  // -------------------------------------------------------------------------
+  // Chat loading
+  // -------------------------------------------------------------------------
+
+  /**
+   * Load all chats in a list (active or archived) via GetDialogs.
+   * Fetches in 100-chat batches until all loaded.
+   *
+   * @param listType - 'active' or 'archived'
+   * @param whenFirstBatchDone - callback fired after the first batch completes
+   */
+  private async loadAllChats(
+    listType: "active" | "archived",
+    whenFirstBatchDone?: () => Promise<void>,
+  ): Promise<void> {
+    const userId = this.userId!;
+    const isArchived = listType === "archived";
+    let isFirstBatch = true;
+    let offsetDate = 0;
+    let offsetId = 0;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let offsetPeer: any = new Api.InputPeerEmpty();
+    let iterations = 0;
+
+    console.log(LOG_PREFIX, `Loading ${listType} chats...`);
+
+    // Also fetch pinned dialogs on first active batch
+    if (!isArchived) {
+      try {
+        const pinned = await mtprotoService.invoke<Api.messages.PeerDialogs>(
+          new Api.messages.GetPinnedDialogs({ folderId: 0 }),
+        );
+        if (pinned?.dialogs?.length) {
+          this.processDialogsResult(pinned, userId, true);
+        }
+      } catch (e) {
+        console.warn(LOG_PREFIX, "Failed to fetch pinned dialogs:", e);
+      }
+    }
+
+    while (iterations < INFINITE_LOOP_MARKER) {
+      iterations++;
+
+      const result = await mtprotoService.invoke<Api.messages.TypeDialogs>(
+        new Api.messages.GetDialogs({
+          offsetDate,
+          offsetId,
+          offsetPeer,
+          limit: CHAT_LIST_LOAD_SLICE,
+          folderId: isArchived ? 1 : 0,
+          hash: bigInt(0),
+        }),
+      );
+
+      // Handle different response types
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const dialogs: any[] = (result as any).dialogs ?? [];
+      if (dialogs.length === 0) {
+        console.log(
+          LOG_PREFIX,
+          `${listType} chats fully loaded (${iterations} batches)`,
+        );
+        break;
+      }
+
+      // Process this batch
+      const chatIds = this.processDialogsResult(result, userId, isFirstBatch);
+
+      // Fire first-batch callback
+      if (isFirstBatch && whenFirstBatchDone) {
+        isFirstBatch = false;
+        await whenFirstBatchDone();
+      } else {
+        isFirstBatch = false;
+      }
+
+      // Check if we've loaded everything
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const totalCount = (result as any).count;
+      if (totalCount !== undefined && chatIds.length === 0) {
+        break;
+      }
+      if (dialogs.length < CHAT_LIST_LOAD_SLICE) {
+        console.log(
+          LOG_PREFIX,
+          `${listType} chats fully loaded (last batch < slice)`,
+        );
+        break;
+      }
+
+      // Prepare pagination offsets from the last dialog
+      const lastDialog = dialogs[dialogs.length - 1];
+      const lastPeerId = buildPeerId(lastDialog.peer);
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const entityMap = buildEntityMap(result as any);
+      const lastEntity = entityMap.get(lastPeerId);
+
+      // Get offset info from the last message in the batch
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const rawMessages: any[] = (result as any).messages ?? [];
+      if (rawMessages.length > 0) {
+        const lastMsg = rawMessages[rawMessages.length - 1];
+        offsetDate = lastMsg.date ?? 0;
+        offsetId = lastMsg.id ?? 0;
+      }
+
+      // Build offset peer for pagination
+      if (lastEntity) {
+        const className: string = lastEntity.className ?? "";
+        if (className === "User") {
+          offsetPeer = new Api.InputPeerUser({
+            userId: bigInt(lastPeerId),
+            accessHash: bigInt(lastEntity.accessHash ?? 0),
+          });
+        } else if (className === "Channel") {
+          offsetPeer = new Api.InputPeerChannel({
+            channelId: bigInt(lastPeerId),
+            accessHash: bigInt(lastEntity.accessHash ?? 0),
+          });
+        } else {
+          offsetPeer = new Api.InputPeerChat({
+            chatId: bigInt(lastPeerId),
+          });
+        }
+      }
+
+      // No explicit delay between batches — sequential await paces naturally
+    }
+
+    if (iterations >= INFINITE_LOOP_MARKER) {
+      console.warn(LOG_PREFIX, `${listType} chat loading hit loop guard`);
+    }
+  }
+
+  /**
+   * Process a GetDialogs response — extract chats, users, messages
+   * and dispatch to Redux.
+   *
+   * @returns Array of chat IDs from this batch
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private processDialogsResult(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    result: any,
+    userId: string,
+    isFirstBatch: boolean,
+  ): string[] {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const dialogs: any[] = result.dialogs ?? [];
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const rawMessages: any[] = result.messages ?? [];
+
+    // Build entity map (users + chats/channels indexed by ID)
+    const entityMap = buildEntityMap(result);
+
+    // Build message map for last-message lookup
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const messageByPeerId = new Map<string, any>();
+    for (const msg of rawMessages) {
+      if (msg?.peerId) {
+        const peerId = buildPeerId(msg.peerId);
+        if (peerId) {
+          // Keep the most recent message per peer
+          const existing = messageByPeerId.get(peerId);
+          if (!existing || (msg.date && msg.date > (existing.date ?? 0))) {
+            messageByPeerId.set(peerId, msg);
+          }
+        }
+      }
+    }
+
+    // Build chats
+    const chats: Record<string, TelegramChat> = {};
+    const chatOrder: string[] = [];
+
+    for (const dialog of dialogs) {
+      const peerId = buildPeerId(dialog.peer);
+      if (!peerId) continue;
+
+      const entity = entityMap.get(peerId);
+      const rawLastMsg = messageByPeerId.get(peerId);
+      const lastMsg = rawLastMsg ? buildMessage(rawLastMsg, peerId) : undefined;
+      const chat = buildChat(dialog, entity, lastMsg ?? undefined);
+
+      chats[chat.id] = chat;
+      chatOrder.push(chat.id);
+    }
+
+    // Build users
+    const users: Record<string, TelegramUser> = {};
+    const rawUsers: unknown[] = result.users ?? [];
+    for (const raw of rawUsers) {
+      const u = buildUser(raw);
+      if (u) users[u.id] = u;
+    }
+
+    // Store channel PTS for update tracking
+    for (const dialog of dialogs) {
+      if (dialog.pts && dialog.peer?.channelId) {
+        const channelId = String(dialog.peer.channelId);
+        store.dispatch(setChannelPts({ userId, channelId, pts: dialog.pts }));
+        updateManager.setChannelPts(channelId, dialog.pts);
+      }
+    }
+
+    // Dispatch to Redux
+    if (isFirstBatch) {
+      store.dispatch(replaceChats({ userId, chats, chatsOrder: chatOrder }));
+      store.dispatch(setUsers({ userId, users }));
+    } else {
+      store.dispatch(addChats({ userId, chats, appendOrder: chatOrder }));
+      store.dispatch(addUsers({ userId, users }));
+    }
+
+    return chatOrder;
+  }
+
+  // -------------------------------------------------------------------------
+  // Message loading
+  // -------------------------------------------------------------------------
+
+  /**
+   * Load messages for the currently open chat.
+   * Uses the same slice sizes (60 desktop / 40 mobile).
+   */
+  private async loadAndReplaceMessages(): Promise<void> {
+    const userId = this.userId!;
+    const state = store.getState();
+    const userState = state.telegram.byUser[userId];
+    const selectedChatId = userState?.selectedChatId;
+
+    if (!selectedChatId) {
+      console.log(LOG_PREFIX, "No chat selected, skipping message load");
+      return;
+    }
+
+    const slice = getMessageSlice();
+
+    try {
+      console.log(
+        LOG_PREFIX,
+        `Loading ${slice} messages for chat ${selectedChatId}`,
+      );
+
+      const result = await mtprotoService.invoke(
+        new Api.messages.GetHistory({
+          peer: selectedChatId,
+          offsetId: 0,
+          addOffset: 0,
+          limit: slice,
+        }),
+      );
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const rawMessages: any[] = (result as any)?.messages ?? [];
+      const messages = rawMessages
+        .map((m) => buildMessage(m, selectedChatId))
+        .filter(Boolean) as NonNullable<ReturnType<typeof buildMessage>>[];
+
+      if (messages.length > 0) {
+        store.dispatch(
+          addChatMessagesById({ userId, chatId: selectedChatId, messages }),
+        );
+      }
+
+      console.log(
+        LOG_PREFIX,
+        `Loaded ${messages.length} messages for chat ${selectedChatId}`,
+      );
+    } catch (error) {
+      console.warn(
+        LOG_PREFIX,
+        `Failed to load messages for chat ${selectedChatId}:`,
+        error,
+      );
+    }
+  }
+
+  /**
+   * Background preload: fetch messages for the top 20 chats.
+   * 100ms pause between each to avoid rate limits.
+   */
+  private async preloadTopChatMessages(): Promise<void> {
+    const userId = this.userId!;
+    const state = store.getState();
+    const userState = state.telegram.byUser[userId];
+    if (!userState) return;
+
+    const chatsOrder = userState.chatsOrder;
+    const selectedChatId = userState.selectedChatId;
+    const slice = getMessageSlice();
+
+    let preloaded = 0;
+
+    for (const chatId of chatsOrder) {
+      if (preloaded >= TOP_CHAT_MESSAGES_PRELOAD_LIMIT) break;
+
+      // Skip the already-loaded selected chat
+      if (chatId === selectedChatId) continue;
+
+      // Skip if we already have messages for this chat
+      if (
+        userState.messages[chatId] &&
+        Object.keys(userState.messages[chatId]).length > 0
+      ) {
+        continue;
+      }
+
+      await pause(TOP_CHAT_MESSAGES_PRELOAD_INTERVAL);
+
+      try {
+        const result = await mtprotoService.invoke(
+          new Api.messages.GetHistory({
+            peer: chatId,
+            offsetId: 0,
+            addOffset: 0,
+            limit: slice,
+          }),
+        );
+
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const rawMessages: any[] = (result as any)?.messages ?? [];
+        const messages = rawMessages
+          .map((m) => buildMessage(m, chatId))
+          .filter(Boolean) as NonNullable<ReturnType<typeof buildMessage>>[];
+
+        if (messages.length > 0) {
+          store.dispatch(addChatMessagesById({ userId, chatId, messages }));
+        }
+
+        preloaded++;
+      } catch (error) {
+        console.warn(
+          LOG_PREFIX,
+          `Failed to preload messages for chat ${chatId}:`,
+          error,
+        );
+        // Continue with next chat
+      }
+    }
+
+    console.log(LOG_PREFIX, `Preloaded messages for ${preloaded} chats`);
+  }
+}
+
+export const telegramSyncService = new TelegramSyncService();
diff --git a/src/services/telegram/updateHandler.ts b/src/services/telegram/updateHandler.ts
new file mode 100644
index 000000000..21adc5ec9
--- /dev/null
+++ b/src/services/telegram/updateHandler.ts
@@ -0,0 +1,190 @@
+/**
+ * Update handler — routes processed Telegram updates to Redux dispatches.
+ *
+ * Only handles essential update types:
+ * - New/edit/delete messages
+ * - Read status changes
+ * - Chat metadata updates
+ */
+
+import { Api } from "telegram/tl";
+import { store } from "../../store";
+import {
+  addMessage,
+  updateMessage,
+  deleteChatMessages,
+  updateChat,
+} from "../../store/telegram";
+import { buildMessage, buildPeerId } from "./entityBuilders";
+
+const LOG_PREFIX = "[TelegramSync]";
+
+/**
+ * Handle a single update from the UpdateManager.
+ * Called for both real-time updates and difference-recovery updates.
+ */
+export function handleUpdate(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  update: any,
+  userId: string,
+  _source: "realtime" | "difference" = "realtime",
+): void {
+  const dispatch = store.dispatch;
+
+  // -------------------------------------------------------------------------
+  // Force sync signal from UpdateManager
+  // -------------------------------------------------------------------------
+  if (update && update._ === "forceSync") {
+    console.log(
+      LOG_PREFIX,
+      "Force sync requested",
+      update.channelId ? `for channel ${update.channelId}` : "(full)",
+    );
+    return;
+  }
+
+  // -------------------------------------------------------------------------
+  // New messages
+  // -------------------------------------------------------------------------
+  if (
+    update instanceof Api.UpdateNewMessage ||
+    update instanceof Api.UpdateNewChannelMessage
+  ) {
+    const msg = buildMessage(update.message);
+    if (msg) {
+      dispatch(addMessage({ userId, message: msg }));
+      dispatch(
+        updateChat({
+          userId,
+          id: msg.chatId,
+          updates: {
+            lastMessage: msg,
+            lastMessageDate: msg.date,
+          },
+        }),
+      );
+    }
+    return;
+  }
+
+  // -------------------------------------------------------------------------
+  // Edited messages
+  // -------------------------------------------------------------------------
+  if (
+    update instanceof Api.UpdateEditMessage ||
+    update instanceof Api.UpdateEditChannelMessage
+  ) {
+    const msg = buildMessage(update.message);
+    if (msg) {
+      dispatch(
+        updateMessage({
+          userId,
+          chatId: msg.chatId,
+          messageId: msg.id,
+          updates: msg,
+        }),
+      );
+    }
+    return;
+  }
+
+  // -------------------------------------------------------------------------
+  // Deleted messages
+  // -------------------------------------------------------------------------
+  if (update instanceof Api.UpdateDeleteMessages) {
+    const messageIds = update.messages.map(String);
+    // DeleteMessages doesn't include chatId — we need to find it from our state.
+    // For common messages, we search all chats for these message IDs.
+    const state = store.getState();
+    const userState = state.telegram.byUser[userId];
+    if (userState) {
+      for (const chatId of Object.keys(userState.messages)) {
+        const chatMsgs = userState.messages[chatId];
+        const matching = messageIds.filter((id) => chatMsgs[id]);
+        if (matching.length > 0) {
+          dispatch(deleteChatMessages({ userId, chatId, messageIds: matching }));
+        }
+      }
+    }
+    return;
+  }
+
+  if (update instanceof Api.UpdateDeleteChannelMessages) {
+    const channelId = String(update.channelId);
+    const messageIds = update.messages.map(String);
+    dispatch(deleteChatMessages({ userId, chatId: channelId, messageIds }));
+    return;
+  }
+
+  // -------------------------------------------------------------------------
+  // Read status (inbox)
+  // -------------------------------------------------------------------------
+  if (update instanceof Api.UpdateReadHistoryInbox) {
+    const chatId = buildPeerId(update.peer);
+    if (chatId) {
+      dispatch(
+        updateChat({
+          userId,
+          id: chatId,
+          updates: { unreadCount: update.stillUnreadCount },
+        }),
+      );
+    }
+    return;
+  }
+
+  // Read status (outbox) — no direct UI action needed for outbox reads typically
+  if (update instanceof Api.UpdateReadHistoryOutbox) {
+    return;
+  }
+
+  // Channel read
+  if (update instanceof Api.UpdateReadChannelInbox) {
+    const chatId = String(update.channelId);
+    dispatch(
+      updateChat({
+        userId,
+        id: chatId,
+        updates: { unreadCount: update.stillUnreadCount },
+      }),
+    );
+    return;
+  }
+
+  // -------------------------------------------------------------------------
+  // Chat/channel metadata updates
+  // -------------------------------------------------------------------------
+  if (update instanceof Api.UpdateChannel) {
+    // The UpdateChannel event only gives us the channel ID.
+    // Full re-fetch is handled by sync service if needed.
+    return;
+  }
+
+  // -------------------------------------------------------------------------
+  // User status (online/offline) — could extend TelegramUser in future
+  // -------------------------------------------------------------------------
+  if (update instanceof Api.UpdateUserStatus) {
+    return;
+  }
+
+  // -------------------------------------------------------------------------
+  // Raw messages from difference (not wrapped in Update*)
+  // -------------------------------------------------------------------------
+  if (update instanceof Api.Message || update instanceof Api.MessageService) {
+    const msg = buildMessage(update);
+    if (msg) {
+      dispatch(addMessage({ userId, message: msg }));
+      dispatch(
+        updateChat({
+          userId,
+          id: msg.chatId,
+          updates: {
+            lastMessage: msg,
+            lastMessageDate: msg.date,
+          },
+        }),
+      );
+    }
+    return;
+  }
+}
diff --git a/src/services/updateManager.test.ts b/src/services/updateManager.test.ts
new file mode 100644
index 000000000..74c8122b8
--- /dev/null
+++ b/src/services/updateManager.test.ts
@@ -0,0 +1,676 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import type { Mock } from "vitest";
+import type { TelegramClient } from "telegram";
+
+// Mock telegram/tl
+vi.mock("telegram/tl", () => ({
+  Api: {
+    Updates: class Updates {
+      updates!: any[];
+      seq!: number;
+      date!: number;
+      seqStart?: number;
+      constructor(p: any) {
+        Object.assign(this, p);
+      }
+    },
+    UpdatesCombined: class UpdatesCombined {
+      updates!: any[];
+      seq!: number;
+      seqStart!: number;
+      date!: number;
+      constructor(p: any) {
+        Object.assign(this, p);
+      }
+    },
+    UpdateShort: class UpdateShort {
+      update!: any;
+      constructor(p: any) {
+        Object.assign(this, p);
+      }
+    },
+    updates: {
+      GetDifference: class GetDifference {
+        constructor(public params: any) {}
+      },
+      Difference: class Difference {
+        state!: any;
+        newMessages!: any[];
+        otherUpdates!: any[];
+        constructor(p: any) {
+          Object.assign(this, p);
+        }
+      },
+      DifferenceSlice: class DifferenceSlice {
+        intermediateState!: any;
+        newMessages!: any[];
+        otherUpdates!: any[];
+        constructor(p: any) {
+          Object.assign(this, p);
+        }
+      },
+      DifferenceEmpty: class DifferenceEmpty {},
+      DifferenceTooLong: class DifferenceTooLong {
+        pts!: number;
+        constructor(p: any) {
+          Object.assign(this, p);
+        }
+      },
+      GetChannelDifference: class GetChannelDifference {
+        constructor(public params: any) {}
+      },
+      ChannelDifference: class ChannelDifference {
+        pts!: number;
+        final!: boolean;
+        newMessages!: any[];
+        otherUpdates!: any[];
+        constructor(p: any) {
+          Object.assign(this, p);
+        }
+      },
+      ChannelDifferenceTooLong: class ChannelDifferenceTooLong {
+        pts!: number;
+        constructor(p: any) {
+          Object.assign(this, p);
+        }
+      },
+      ChannelDifferenceEmpty: class ChannelDifferenceEmpty {},
+    },
+    InputChannel: class InputChannel {
+      constructor(public params: any) {}
+    },
+    ChannelMessagesFilterEmpty: class ChannelMessagesFilterEmpty {},
+  },
+}));
+
+vi.mock("big-integer", () => ({ default: (v: any) => v }));
+vi.mock("../lib/mcp/logger");
+
+import { UpdateManager } from "./updateManager";
+import { Api } from "telegram/tl";
+
+function createMockClient(): TelegramClient {
+  return {
+    invoke: vi.fn(),
+  } as unknown as TelegramClient;
+}
+
+describe("UpdateManager", () => {
+  let manager: UpdateManager;
+  let mockClient: TelegramClient;
+  let mockHandler: Mock;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    manager = new UpdateManager();
+    mockClient = createMockClient();
+    mockHandler = vi.fn();
+  });
+
+  afterEach(() => {
+    manager.destroy();
+    vi.useRealTimers();
+  });
+
+  describe("Initialization", () => {
+    it("should initialize with client and handler", () => {
+      manager.init(mockClient, mockHandler);
+      expect(manager).toBeDefined();
+    });
+
+    it("should set initial state", () => {
+      manager.setInitialState({ seq: 10, pts: 20, qts: 5, date: 1000 });
+      const state = manager.getCommonBoxState();
+      expect(state).toEqual({ seq: 10, pts: 20, qts: 5, date: 1000 });
+    });
+
+    it("should set partial initial state", () => {
+      manager.setInitialState({ seq: 10, pts: 20 });
+      const state = manager.getCommonBoxState();
+      expect(state.seq).toBe(10);
+      expect(state.pts).toBe(20);
+      expect(state.qts).toBe(0);
+      expect(state.date).toBe(0);
+    });
+
+    it("should set channel pts", () => {
+      manager.setChannelPts("123", 50);
+      const ptsMap = manager.getChannelPtsMap();
+      expect(ptsMap["123"]).toBe(50);
+    });
+
+    it("should return copy of common box state", () => {
+      manager.setInitialState({ seq: 10 });
+      const state1 = manager.getCommonBoxState();
+      const state2 = manager.getCommonBoxState();
+      expect(state1).not.toBe(state2);
+      expect(state1).toEqual(state2);
+    });
+  });
+
+  describe("Update delivery", () => {
+    beforeEach(() => {
+      manager.init(mockClient, mockHandler);
+    });
+
+    it("should deliver plain update directly to handler", () => {
+      const update = { _: "updateCustom", data: "test" } as any;
+      manager.processUpdate(update);
+      expect(mockHandler).toHaveBeenCalledWith(update, "realtime");
+    });
+
+    it("should route UpdateShort to pts processing", () => {
+      const innerUpdate = { _: "updateTest", pts: 1, ptsCount: 1 } as any;
+      const update = new Api.UpdateShort({ update: innerUpdate, date: 1000 } as any);
+      manager.setInitialState({ pts: 0 } as any);
+      manager.processUpdate(update);
+      expect(mockHandler).toHaveBeenCalledWith(innerUpdate, "realtime");
+    });
+
+    it("should deliver update with pts to handler when sequence matches", () => {
+      manager.setInitialState({ pts: 0 } as any);
+      const update = { _: "updateTest", pts: 1, ptsCount: 1 } as any;
+      manager.processUpdate(update);
+      expect(mockHandler).toHaveBeenCalledWith(update, "realtime");
+    });
+  });
+
+  describe("SEQ queue", () => {
+    beforeEach(() => {
+      manager.init(mockClient, mockHandler);
+      manager.setInitialState({ seq: 0 } as any);
+    });
+
+    it("should deliver sequential seq updates in order", () => {
+      const update1 = new Api.Updates({
+        updates: [{ _: "update1" } as any],
+        users: [] as any,
+        chats: [] as any,
+        seq: 1,
+        date: 1000,
+      } as any);
+      const update2 = new Api.Updates({
+        updates: [{ _: "update2" } as any],
+        users: [] as any,
+        chats: [] as any,
+        seq: 2,
+        date: 2000,
+      } as any);
+
+      manager.processUpdate(update1);
+      manager.processUpdate(update2);
+
+      expect(mockHandler).toHaveBeenCalledWith({ _: "update1" } as any, "realtime");
+      expect(mockHandler).toHaveBeenCalledWith({ _: "update2" } as any, "realtime");
+      expect(manager.getCommonBoxState().seq).toBe(2);
+    });
+
+    it("should queue out-of-order seq updates and deliver when gap fills", () => {
+      const update1 = new Api.Updates({
+        updates: [{ _: "update1" } as any],
+        users: [] as any,
+        chats: [] as any,
+        seq: 1,
+        date: 1000,
+      } as any);
+      const update3 = new Api.Updates({
+        updates: [{ _: "update3" } as any],
+        users: [] as any,
+        chats: [] as any,
+        seq: 3,
+        date: 3000,
+      } as any);
+      const update2 = new Api.Updates({
+        updates: [{ _: "update2" } as any],
+        users: [] as any,
+        chats: [] as any,
+        seq: 2,
+        date: 2000,
+      } as any);
+
+      manager.processUpdate(update1);
+      manager.processUpdate(update3); // Gap detected
+      expect(mockHandler).toHaveBeenCalledTimes(1); // Only update1
+
+      manager.processUpdate(update2); // Fills gap
+      expect(mockHandler).toHaveBeenCalledWith({ _: "update2" } as any, "realtime");
+      expect(mockHandler).toHaveBeenCalledWith({ _: "update3" } as any, "realtime");
+      expect(manager.getCommonBoxState().seq).toBe(3);
+    });
+
+    it("should skip duplicate seq updates", () => {
+      const update1 = new Api.Updates({
+        updates: [{ _: "update1" } as any],
+        users: [] as any,
+        chats: [] as any,
+        seq: 1,
+        date: 1000,
+      } as any);
+      const update1Dup = new Api.Updates({
+        updates: [{ _: "update1dup" } as any],
+        users: [] as any,
+        chats: [] as any,
+        seq: 1,
+        date: 1000,
+      } as any);
+
+      manager.processUpdate(update1);
+      manager.processUpdate(update1Dup);
+
+      expect(mockHandler).toHaveBeenCalledWith({ _: "update1" } as any, "realtime");
+      expect(mockHandler).not.toHaveBeenCalledWith({ _: "update1dup" } as any, "realtime");
+      expect(mockHandler).toHaveBeenCalledTimes(1);
+    });
+
+    it("should handle UpdatesCombined with seqStart", () => {
+      const update = new Api.UpdatesCombined({
+        updates: [{ _: "update1" } as any, { _: "update2" } as any],
+        users: [] as any,
+        chats: [] as any,
+        seqStart: 1,
+        seq: 2,
+        date: 1000,
+      } as any);
+
+      manager.processUpdate(update);
+
+      expect(mockHandler).toHaveBeenCalledWith({ _: "update1" } as any, "realtime");
+      expect(mockHandler).toHaveBeenCalledWith({ _: "update2" } as any, "realtime");
+      expect(manager.getCommonBoxState().seq).toBe(2);
+    });
+
+    it("should handle Updates with seq=0 (no sequencing)", () => {
+      manager.setInitialState({ pts: 0 } as any);
+      const update = new Api.Updates({
+        updates: [
+          { _: "update1", pts: 1, ptsCount: 1 } as any,
+          { _: "update2", pts: 2, ptsCount: 1 } as any,
+        ],
+        users: [] as any,
+        chats: [] as any,
+        seq: 0,
+        date: 1000,
+      } as any);
+
+      manager.processUpdate(update);
+
+      expect(mockHandler).toHaveBeenCalledWith({ _: "update1", pts: 1, ptsCount: 1 } as any, "realtime");
+      expect(mockHandler).toHaveBeenCalledWith({ _: "update2", pts: 2, ptsCount: 1 } as any, "realtime");
+      expect(manager.getCommonBoxState().seq).toBe(0); // Seq not updated
+    });
+  });
+
+  describe("PTS queue", () => {
+    beforeEach(() => {
+      manager.init(mockClient, mockHandler);
+      manager.setInitialState({ pts: 0 } as any);
+    });
+
+    it("should deliver common box PTS update in correct sequence", () => {
+      const update = { _: "updateTest", pts: 1, ptsCount: 1 } as any;
+      manager.processUpdate(update);
+      expect(mockHandler).toHaveBeenCalledWith(update, "realtime");
+      expect(manager.getCommonBoxState().pts).toBe(1);
+    });
+
+    it("should skip duplicate PTS updates", () => {
+      const update1 = { _: "update1", pts: 1, ptsCount: 1 } as any;
+      const update1Dup = { _: "update1dup", pts: 1, ptsCount: 1 } as any;
+
+      manager.processUpdate(update1);
+      manager.processUpdate(update1Dup);
+
+      expect(mockHandler).toHaveBeenCalledWith(update1, "realtime");
+      expect(mockHandler).not.toHaveBeenCalledWith(update1Dup, "realtime");
+      expect(mockHandler).toHaveBeenCalledTimes(1);
+    });
+
+    it("should route channel PTS update to channel queue", () => {
+      manager.setChannelPts("123", 0);
+      const update = {
+        _: "updateNewChannelMessage",
+        pts: 1,
+        ptsCount: 1,
+        message: {
+          peerId: { channelId: "123" },
+        },
+      } as any;
+
+      manager.processUpdate(update);
+      expect(mockHandler).toHaveBeenCalledWith(update, "realtime");
+      expect(manager.getChannelPtsMap()["123"]).toBe(1);
+    });
+
+    it("should handle out-of-order PTS updates when gap fills", () => {
+      const update1 = { _: "update1", pts: 1, ptsCount: 1 } as any;
+      const update3 = { _: "update3", pts: 3, ptsCount: 1 } as any;
+      const update2 = { _: "update2", pts: 2, ptsCount: 1 } as any;
+
+      manager.processUpdate(update1);
+      manager.processUpdate(update3); // Gap — queued but not delivered
+      expect(mockHandler).toHaveBeenCalledTimes(1);
+
+      manager.processUpdate(update2); // Fills gap — delivers update2
+      expect(mockHandler).toHaveBeenCalledWith(update2, "realtime");
+      // Note: drainPtsQueue uses a const localPts snapshot, so update3
+      // cannot be delivered in the same drain pass. It remains queued
+      // until the next drain or gap recovery triggers.
+      expect(mockHandler).toHaveBeenCalledTimes(2);
+      expect(manager.getCommonBoxState().pts).toBe(2);
+    });
+
+    it("should handle pts=0 ptsCount=0 case", () => {
+      manager.setInitialState({ pts: 0 } as any);
+      const update = { _: "updateTest", pts: 0, ptsCount: 0 } as any;
+      manager.processUpdate(update);
+      expect(mockHandler).toHaveBeenCalledWith(update, "realtime");
+    });
+  });
+
+  describe("Gap recovery", () => {
+    beforeEach(() => {
+      manager.init(mockClient, mockHandler);
+      manager.setInitialState({ seq: 0, pts: 0, qts: 0, date: 1000 } as any);
+    });
+
+    it("should schedule gap recovery after delay on SEQ gap", () => {
+      const update = new Api.Updates({
+        updates: [{ _: "update" } as any],
+        users: [] as any,
+        chats: [] as any,
+        seq: 5, // Gap: expected seq=1
+        date: 2000,
+      } as any);
+
+      manager.processUpdate(update);
+
+      // Should not call getDifference immediately
+      expect(mockClient.invoke).not.toHaveBeenCalled();
+
+      // Advance timers
+      vi.advanceTimersByTime(500);
+
+      // Should now call getDifference
+      expect(mockClient.invoke).toHaveBeenCalled();
+    });
+
+    it("should call getDifference on gap recovery", async () => {
+      const mockDifference = new Api.updates.Difference({
+        state: { pts: 10, seq: 5, date: 2000, qts: 5 } as any,
+        newMessages: [{ _: "message1" } as any],
+        newEncryptedMessages: [] as any,
+        otherUpdates: [{ _: "update1" } as any],
+        chats: [] as any,
+        users: [] as any,
+      });
+
+      vi.mocked(mockClient.invoke).mockResolvedValue(mockDifference);
+
+      const update = new Api.Updates({
+        updates: [{ _: "update" } as any],
+        users: [] as any,
+        chats: [] as any,
+        seq: 5,
+        date: 2000,
+      } as any);
+
+      manager.processUpdate(update);
+      vi.advanceTimersByTime(500);
+
+      await vi.runAllTimersAsync();
+
+      expect(mockClient.invoke).toHaveBeenCalledWith(
+        expect.objectContaining({
+          params: expect.objectContaining({
+            pts: 0,
+            date: 1000,
+            qts: 0,
+          }),
+        })
+      );
+
+      expect(mockHandler).toHaveBeenCalledWith({ _: "message1" } as any, "difference");
+      expect(mockHandler).toHaveBeenCalledWith({ _: "update1" } as any, "difference");
+      expect(manager.getCommonBoxState().pts).toBe(10);
+      expect(manager.getCommonBoxState().seq).toBe(5);
+    });
+
+    it("should handle DifferenceSlice and recurse", async () => {
+      const slice = new Api.updates.DifferenceSlice({
+        intermediateState: { pts: 5, seq: 2, date: 1500, qts: 2 } as any,
+        newMessages: [{ _: "msg1" } as any],
+        newEncryptedMessages: [] as any,
+        otherUpdates: [{ _: "upd1" } as any],
+        chats: [] as any,
+        users: [] as any,
+      });
+
+      const final = new Api.updates.Difference({
+        state: { pts: 10, seq: 5, date: 2000, qts: 5 } as any,
+        newMessages: [{ _: "msg2" } as any],
+        newEncryptedMessages: [] as any,
+        otherUpdates: [{ _: "upd2" } as any],
+        chats: [] as any,
+        users: [] as any,
+      });
+
+      vi.mocked(mockClient.invoke)
+        .mockResolvedValueOnce(slice)
+        .mockResolvedValueOnce(final);
+
+      const update = new Api.Updates({
+        updates: [{ _: "update" } as any],
+        users: [] as any,
+        chats: [] as any,
+        seq: 10,
+        date: 3000,
+      } as any);
+
+      manager.processUpdate(update);
+      vi.advanceTimersByTime(500);
+      await vi.runAllTimersAsync();
+
+      expect(mockClient.invoke).toHaveBeenCalledTimes(2);
+      expect(mockHandler).toHaveBeenCalledWith({ _: "msg1" } as any, "difference");
+      expect(mockHandler).toHaveBeenCalledWith({ _: "upd1" } as any, "difference");
+      expect(mockHandler).toHaveBeenCalledWith({ _: "msg2" } as any, "difference");
+      expect(mockHandler).toHaveBeenCalledWith({ _: "upd2" } as any, "difference");
+      expect(manager.getCommonBoxState().pts).toBe(10);
+    });
+
+    it("should force full sync after max recovery attempts", async () => {
+      vi.mocked(mockClient.invoke).mockRejectedValue(new Error("Network error"));
+
+      const update = new Api.Updates({
+        updates: [{ _: "update" } as any],
+        users: [] as any,
+        chats: [] as any,
+        seq: 5,
+        date: 2000,
+      } as any);
+
+      // Trigger gap
+      manager.processUpdate(update);
+
+      // Attempt 1
+      vi.advanceTimersByTime(500);
+      await vi.runAllTimersAsync();
+
+      // Attempt 2
+      manager.processUpdate(update);
+      vi.advanceTimersByTime(500);
+      await vi.runAllTimersAsync();
+
+      // Attempt 3
+      manager.processUpdate(update);
+      vi.advanceTimersByTime(500);
+      await vi.runAllTimersAsync();
+
+      // Should give up and force sync
+      manager.processUpdate(update);
+      vi.advanceTimersByTime(500);
+      await vi.runAllTimersAsync();
+
+      expect(mockHandler).toHaveBeenCalledWith(
+        { _: "forceSync", channelId: null } as any,
+        "difference"
+      );
+    });
+
+    it("should not schedule recovery if already recovering", async () => {
+      vi.mocked(mockClient.invoke).mockImplementation(
+        () => new Promise((resolve) => setTimeout(resolve, 10000))
+      );
+
+      const update = new Api.Updates({
+        updates: [{ _: "update" } as any],
+        users: [] as any,
+        chats: [] as any,
+        seq: 5,
+        date: 2000,
+      } as any);
+
+      manager.processUpdate(update);
+      vi.advanceTimersByTime(500);
+
+      // Start recovery
+      await Promise.resolve();
+
+      // Try to trigger another recovery
+      const update2 = new Api.Updates({
+        updates: [{ _: "update2" } as any],
+        users: [] as any,
+        chats: [] as any,
+        seq: 10,
+        date: 3000,
+      } as any);
+      manager.processUpdate(update2);
+
+      expect(mockClient.invoke).toHaveBeenCalledTimes(1); // Only once
+    });
+  });
+
+  describe("extractChannelId", () => {
+    beforeEach(() => {
+      manager.init(mockClient, mockHandler);
+    });
+
+    it("should extract channelId from message.peerId.channelId", () => {
+      manager.setChannelPts("123", 0);
+      const update = {
+        _: "updateNewChannelMessage",
+        pts: 1,
+        ptsCount: 1,
+        message: {
+          peerId: { channelId: "123" },
+        },
+      } as any;
+
+      manager.processUpdate(update);
+      expect(manager.getChannelPtsMap()["123"]).toBe(1);
+    });
+
+    it("should extract channelId directly from update", () => {
+      manager.setChannelPts("456", 0);
+      const update = {
+        _: "updateChannelTooLong",
+        pts: 1,
+        ptsCount: 1,
+        channelId: "456",
+      } as any;
+
+      manager.processUpdate(update);
+      expect(manager.getChannelPtsMap()["456"]).toBe(1);
+    });
+
+    it("should return undefined for non-channel updates", () => {
+      manager.setInitialState({ pts: 0 } as any);
+      const update = {
+        _: "updateUserStatus",
+        pts: 1,
+        ptsCount: 1,
+      } as any;
+
+      manager.processUpdate(update);
+      expect(manager.getCommonBoxState().pts).toBe(1); // Common box PTS updated
+    });
+  });
+
+  describe("Destroy", () => {
+    it("should clear timers and null client/handler", () => {
+      manager.init(mockClient, mockHandler);
+
+      const update = new Api.Updates({
+        updates: [{ _: "update" } as any],
+        users: [] as any,
+        chats: [] as any,
+        seq: 5,
+        date: 2000,
+      } as any);
+
+      manager.processUpdate(update); // Triggers gap recovery timer
+
+      manager.destroy();
+
+      vi.advanceTimersByTime(500);
+
+      // Timer should be cleared, no invoke
+      expect(mockClient.invoke).not.toHaveBeenCalled();
+    });
+
+    it("should clear all queues", () => {
+      manager.init(mockClient, mockHandler);
+      manager.setInitialState({ seq: 0, pts: 0 } as any);
+
+      const update = new Api.Updates({
+        updates: [{ _: "update" } as any],
+        users: [] as any,
+        chats: [] as any,
+        seq: 5,
+        date: 2000,
+      } as any);
+
+      manager.processUpdate(update); // Adds to queue
+
+      manager.destroy();
+
+      // After destroy, processing new update should not access old queues
+      manager.init(mockClient, mockHandler);
+      manager.setInitialState({ seq: 0 } as any);
+
+      const update2 = new Api.Updates({
+        updates: [{ _: "update2" } as any],
+        users: [] as any,
+        chats: [] as any,
+        seq: 1,
+        date: 3000,
+      } as any);
+
+      manager.processUpdate(update2);
+      expect(mockHandler).toHaveBeenCalledWith({ _: "update2" } as any, "realtime");
+    });
+  });
+
+  describe("Handler error handling", () => {
+    it("should catch and log handler errors", () => {
+      const errorHandler = vi.fn(() => {
+        throw new Error("Handler error");
+      });
+
+      const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+      manager.init(mockClient, errorHandler);
+      const update = { _: "updateTest" } as any;
+
+      manager.processUpdate(update);
+
+      expect(errorHandler).toHaveBeenCalled();
+      expect(consoleSpy).toHaveBeenCalledWith(
+        "[UpdateManager] Handler error:",
+        expect.any(Error)
+      );
+
+      consoleSpy.mockRestore();
+    });
+  });
+});
diff --git a/src/services/updateManager.ts b/src/services/updateManager.ts
index 48877bffb..7928bdf27 100644
--- a/src/services/updateManager.ts
+++ b/src/services/updateManager.ts
@@ -4,8 +4,6 @@
  * Tracks pts/qts/seq state for the common update box and per-channel PTS.
  * Implements sorted queues for sequential update processing with gap detection
  * and automatic recovery via getDifference / getChannelDifference.
- *
- * Reference: Telegram-TT's src/api/gramjs/updates/updateManager.ts
  */
 
 import { Api } from "telegram/tl";
@@ -168,11 +166,12 @@ export class UpdateManager {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   processUpdate(update: any): void {
     // Combined updates (Updates / UpdatesCombined) contain seq
-    if (update instanceof Api.Updates || update instanceof Api.UpdatesCombined) {
+    if (
+      update instanceof Api.Updates ||
+      update instanceof Api.UpdatesCombined
+    ) {
       const seqStart =
-        update instanceof Api.UpdatesCombined
-          ? update.seqStart
-          : update.seq;
+        update instanceof Api.UpdatesCombined ? update.seqStart : update.seq;
       const seqEnd = update.seq;
 
       if (seqEnd > 0) {
@@ -232,7 +231,9 @@ export class UpdateManager {
       } else {
         // Gap detected — schedule recovery
         mcpWarn(
-          `SEQ gap: expected ${this.commonBoxState.seq + 1}, got ${item.seqStart}`,
+          `SEQ gap: expected ${this.commonBoxState.seq + 1}, got ${
+            item.seqStart
+          }`,
         );
         this.scheduleGapRecovery();
         break;
@@ -251,8 +252,7 @@ export class UpdateManager {
       return;
     }
 
-    const ptsCount =
-      typeof update.ptsCount === "number" ? update.ptsCount : 0;
+    const ptsCount = typeof update.ptsCount === "number" ? update.ptsCount : 0;
 
     // Determine if this is a channel-specific update
     const channelId = this.extractChannelId(update);
@@ -290,7 +290,7 @@ export class UpdateManager {
     const localPts =
       queueKey === "__common__"
         ? this.commonBoxState.pts
-        : (this.channelPtsById[queueKey] ?? 0);
+        : this.channelPtsById[queueKey] ?? 0;
 
     while (queue.length > 0) {
       const item = queue.peek()!;
@@ -340,7 +340,9 @@ export class UpdateManager {
 
     if (this.gapRecoveryAttempts >= MAX_GAP_RECOVERY_ATTEMPTS) {
       mcpWarn(
-        `Gap recovery: max attempts reached${channelId ? ` for channel ${channelId}` : ""}. Forcing full sync.`,
+        `Gap recovery: max attempts reached${
+          channelId ? ` for channel ${channelId}` : ""
+        }. Forcing full sync.`,
       );
       await this.forceSync(channelId);
       return;
@@ -415,7 +417,9 @@ export class UpdateManager {
 
     const pts = this.channelPtsById[channelId] ?? 0;
     if (pts === 0) {
-      mcpWarn(`getChannelDifference: no pts for channel ${channelId}, skipping`);
+      mcpWarn(
+        `getChannelDifference: no pts for channel ${channelId}, skipping`,
+      );
       return;
     }
 
@@ -458,9 +462,7 @@ export class UpdateManager {
 
       this.drainPtsQueue(channelId);
     } catch (error) {
-      mcpWarn(
-        `getChannelDifference failed for ${channelId}: ${error}`,
-      );
+      mcpWarn(`getChannelDifference failed for ${channelId}: ${error}`);
     }
   }
 
@@ -517,7 +519,10 @@ export class UpdateManager {
   }
 
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  private applyDifference(diff: { newMessages: any[]; otherUpdates: any[] }): void {
+  private applyDifference(diff: {
+    newMessages: any[];
+    otherUpdates: any[];
+  }): void {
     for (const msg of diff.newMessages) {
       this.deliver(msg, "difference");
     }
diff --git a/src/store/index.ts b/src/store/index.ts
index 32fd4f9ce..2a749a4d5 100644
--- a/src/store/index.ts
+++ b/src/store/index.ts
@@ -49,6 +49,9 @@ const telegramVolatileTransform = createTransform<
         isLoadingThreads: telegramInitialState.isLoadingThreads,
         // Thread index is volatile — viewport/outlying state is runtime-only
         threadIndex: telegramInitialState.threadIndex,
+        // Sync state is volatile — must re-sync on reload
+        isSyncing: telegramInitialState.isSyncing,
+        isSynced: telegramInitialState.isSynced,
       };
     }
     return cleaned;
diff --git a/src/store/telegram/extraReducers.ts b/src/store/telegram/extraReducers.ts
index cd07d3079..76f80a58a 100644
--- a/src/store/telegram/extraReducers.ts
+++ b/src/store/telegram/extraReducers.ts
@@ -15,7 +15,20 @@ function ensureUser(
   userId: string,
 ): TelegramState {
   if (!state.byUser[userId]) {
-    state.byUser[userId] = { ...initialState };
+    // Create a deep copy of nested objects to avoid sharing references with initialState
+    state.byUser[userId] = {
+      ...initialState,
+      chats: {},
+      chatsOrder: [],
+      messages: {},
+      messagesOrder: {},
+      threads: {},
+      threadsOrder: {},
+      threadIndex: {},
+      users: {},
+      channelPtsById: {},
+      commonBoxState: { ...initialState.commonBoxState },
+    };
   }
   return state.byUser[userId];
 }
diff --git a/src/store/telegram/index.ts b/src/store/telegram/index.ts
index 71a4db798..103cc83dc 100644
--- a/src/store/telegram/index.ts
+++ b/src/store/telegram/index.ts
@@ -15,6 +15,13 @@ const telegramSlice = createSlice({
 });
 
 export const {
+  // Sync state
+  setSyncStatus,
+  setUsers,
+  addUsers,
+  replaceChats,
+  addChats,
+  // Connection / Auth
   setConnectionStatus,
   setConnectionError,
   setAuthStatus,
diff --git a/src/store/telegram/reducers.test.ts b/src/store/telegram/reducers.test.ts
new file mode 100644
index 000000000..8a1b23a40
--- /dev/null
+++ b/src/store/telegram/reducers.test.ts
@@ -0,0 +1,731 @@
+import { configureStore } from "@reduxjs/toolkit";
+import { describe, it, expect, beforeEach, vi } from "vitest";
+
+// Mock redux-persist to avoid persistence layer
+vi.mock("redux-persist", async () => {
+  const actual = await vi.importActual("redux-persist");
+  return {
+    ...actual as object,
+    persistReducer: vi.fn((_config, reducer) => reducer),
+    persistStore: vi.fn(() => ({
+      purge: vi.fn(),
+      flush: vi.fn(),
+      pause: vi.fn(),
+      persist: vi.fn(),
+      rehydrate: vi.fn(),
+    })),
+  };
+});
+
+// Mock the main store exports to prevent store initialization
+vi.mock("../index", () => ({
+  store: { getState: vi.fn(), dispatch: vi.fn(), subscribe: vi.fn(), replaceReducer: vi.fn() },
+  persistor: { purge: vi.fn(), flush: vi.fn() },
+}));
+
+// Now safe to import the telegram slice
+import telegramReducer, {
+  addChat,
+  updateChat,
+  removeChat,
+  replaceChats,
+  addChats,
+  setChatsOrder,
+  addMessage,
+  addMessages,
+  updateMessage,
+  removeMessage,
+  clearMessages,
+  deleteChatMessages,
+  addChatMessagesById,
+  addThread,
+  updateThread,
+  setSelectedThread,
+  setConnectionStatus,
+  setConnectionError,
+  setAuthStatus,
+  setAuthError,
+  setSyncStatus,
+  setCommonBoxState,
+  setChannelPts,
+  resetTelegramForUser,
+  resetChats,
+  resetMessages,
+  setViewportIds,
+  addOutlyingList,
+  setThreadListedIds,
+  setSelectedChat,
+  setPhoneNumber,
+  setSessionString,
+  setCurrentUser,
+  setUsers,
+  addUsers,
+} from "./index";
+
+function createStore() {
+  return configureStore({ reducer: { telegram: telegramReducer } });
+}
+
+const userId = "u1";
+
+describe("Telegram Reducers", () => {
+  describe("Chat Management", () => {
+    let store: ReturnType<typeof createStore>;
+
+    beforeEach(() => {
+      store = createStore();
+    });
+
+    it("addChat: adds chat and prepends to chatsOrder", () => {
+      const chat = { id: "chat1", type: "private" as const, title: "Chat 1", unreadCount: 0, isPinned: false };
+
+      store.dispatch(addChat({ userId, chat }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.chats.chat1).toEqual(chat);
+      expect(state.chatsOrder).toEqual(["chat1"]);
+    });
+
+    it("addChat: prepends new chat to existing order", () => {
+      store.dispatch(addChat({ userId, chat: { id: "chat1", type: "private" as const, unreadCount: 0, isPinned: false } }));
+      store.dispatch(addChat({ userId, chat: { id: "chat2", type: "private" as const, unreadCount: 0, isPinned: false } }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.chatsOrder).toEqual(["chat2", "chat1"]);
+    });
+
+    it("addChat: overwrites existing chat", () => {
+      const chat = { id: "chat1", type: "private" as const, title: "Original", unreadCount: 0, isPinned: false };
+      store.dispatch(addChat({ userId, chat }));
+      store.dispatch(addChat({ userId, chat: { id: "chat1", type: "private" as const, title: "Updated", unreadCount: 0, isPinned: false } }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.chats.chat1.title).toBe("Updated");
+      expect(state.chatsOrder).toEqual(["chat1"]); // Should not add duplicate to order
+    });
+
+    it("updateChat: updates existing chat fields", () => {
+      const chat = { id: "chat1", type: "private" as const, title: "Original", unreadCount: 0, isPinned: false };
+      store.dispatch(addChat({ userId, chat }));
+      store.dispatch(updateChat({ userId, id: "chat1", updates: { title: "Updated" } }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.chats.chat1.title).toBe("Updated");
+      expect(state.chats.chat1.type).toBe("private");
+    });
+
+    it("updateChat: does nothing if chat does not exist", () => {
+      store.dispatch(updateChat({ userId, id: "nonexistent", updates: { title: "Test" } }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.chats.nonexistent).toBeUndefined();
+    });
+
+    it("removeChat: removes from chats and chatsOrder", () => {
+      store.dispatch(addChat({ userId, chat: { id: "chat1", type: "private" as const, unreadCount: 0, isPinned: false } }));
+      store.dispatch(addChat({ userId, chat: { id: "chat2", type: "private" as const, unreadCount: 0, isPinned: false } }));
+      store.dispatch(removeChat({ userId, chatId: "chat1" }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.chats.chat1).toBeUndefined();
+      expect(state.chatsOrder).toEqual(["chat2"]);
+    });
+
+    it("removeChat: clears selectedChatId if it was selected", () => {
+      store.dispatch(addChat({ userId, chat: { id: "chat1", type: "private" as const, unreadCount: 0, isPinned: false } }));
+      store.dispatch(setSelectedChat({ userId, chatId: "chat1" }));
+      store.dispatch(removeChat({ userId, chatId: "chat1" }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.selectedChatId).toBeNull();
+    });
+
+    it("removeChat: keeps selectedChatId if different chat removed", () => {
+      store.dispatch(addChat({ userId, chat: { id: "chat1", type: "private" as const, unreadCount: 0, isPinned: false } }));
+      store.dispatch(addChat({ userId, chat: { id: "chat2", type: "private" as const, unreadCount: 0, isPinned: false } }));
+      store.dispatch(setSelectedChat({ userId, chatId: "chat1" }));
+      store.dispatch(removeChat({ userId, chatId: "chat2" }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.selectedChatId).toBe("chat1");
+    });
+
+    it("replaceChats: replaces all chats and order", () => {
+      store.dispatch(addChat({ userId, chat: { id: "chat1", type: "private" as const, unreadCount: 0, isPinned: false } }));
+
+      const newChats = {
+        chat2: { id: "chat2", type: "group" as const, unreadCount: 0, isPinned: false },
+        chat3: { id: "chat3", type: "channel" as const, unreadCount: 0, isPinned: false },
+      };
+      const newOrder = ["chat2", "chat3"];
+
+      store.dispatch(replaceChats({ userId, chats: newChats, chatsOrder: newOrder }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.chats).toEqual(newChats);
+      expect(state.chatsOrder).toEqual(newOrder);
+    });
+
+    it("addChats: appends new chats and updates order", () => {
+      store.dispatch(addChat({ userId, chat: { id: "chat1", type: "private" as const, unreadCount: 0, isPinned: false } }));
+
+      const newChats = {
+        chat2: { id: "chat2", type: "group" as const, unreadCount: 0, isPinned: false },
+        chat3: { id: "chat3", type: "channel" as const, unreadCount: 0, isPinned: false },
+      };
+      const newOrder = ["chat2", "chat3"];
+
+      store.dispatch(addChats({ userId, chats: newChats, appendOrder: newOrder }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.chats.chat1).toBeDefined();
+      expect(state.chats.chat2).toBeDefined();
+      expect(state.chats.chat3).toBeDefined();
+      expect(state.chatsOrder).toEqual(["chat1", "chat2", "chat3"]);
+    });
+
+    it("addChats: skips duplicates in order", () => {
+      store.dispatch(addChat({ userId, chat: { id: "chat1", type: "private" as const, unreadCount: 0, isPinned: false } }));
+
+      const newChats = {
+        chat1: { id: "chat1", type: "private" as const, unreadCount: 0, isPinned: false },
+        chat2: { id: "chat2", type: "group" as const, unreadCount: 0, isPinned: false },
+      };
+      const newOrder = ["chat1", "chat2"];
+
+      store.dispatch(addChats({ userId, chats: newChats, appendOrder: newOrder }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.chatsOrder).toEqual(["chat1", "chat2"]);
+    });
+
+    it("setChatsOrder: replaces order completely", () => {
+      store.dispatch(addChat({ userId, chat: { id: "chat1", type: "private" as const, unreadCount: 0, isPinned: false } }));
+      store.dispatch(addChat({ userId, chat: { id: "chat2", type: "private" as const, unreadCount: 0, isPinned: false } }));
+
+      store.dispatch(setChatsOrder({ userId, order: ["chat2", "chat1"] }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.chatsOrder).toEqual(["chat2", "chat1"]);
+    });
+  });
+
+  describe("Message Management", () => {
+    let store: ReturnType<typeof createStore>;
+
+    beforeEach(() => {
+      store = createStore();
+      store.dispatch(addChat({ userId, chat: { id: "chat1", type: "private" as const, unreadCount: 0, isPinned: false } }));
+    });
+
+    it("addMessage: adds to messages and messagesOrder", () => {
+      const message = { id: "msg1", chatId: "chat1", date: 1000, fromId: "user1", message: "", isOutgoing: false, isEdited: false, isForwarded: false };
+
+      store.dispatch(addMessage({ userId, message }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.messages.chat1?.msg1).toEqual(message);
+      expect(state.messagesOrder.chat1).toEqual(["msg1"]);
+    });
+
+    it("addMessage: skips duplicate message", () => {
+      const message = { id: "msg1", chatId: "chat1", date: 1000, fromId: "user1", message: "", isOutgoing: false, isEdited: false, isForwarded: false };
+
+      store.dispatch(addMessage({ userId, message }));
+      store.dispatch(addMessage({ userId, message }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.messagesOrder.chat1).toEqual(["msg1"]);
+    });
+
+    it("addMessage: appends to existing messages", () => {
+      store.dispatch(addMessage({ userId, message: { id: "msg1", chatId: "chat1", date: 1000, fromId: "user1", message: "", isOutgoing: false, isEdited: false, isForwarded: false } }));
+      store.dispatch(addMessage({ userId, message: { id: "msg2", chatId: "chat1", date: 2000, fromId: "user1", message: "", isOutgoing: false, isEdited: false, isForwarded: false } }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.messagesOrder.chat1).toEqual(["msg1", "msg2"]);
+    });
+
+    it("addMessages: bulk add messages, skips duplicates", () => {
+      const messages = [
+        { id: "msg1", chatId: "chat1", date: 1000, fromId: "user1", message: "", isOutgoing: false, isEdited: false, isForwarded: false },
+        { id: "msg2", chatId: "chat1", date: 2000, fromId: "user1", message: "", isOutgoing: false, isEdited: false, isForwarded: false },
+        { id: "msg3", chatId: "chat1", date: 3000, fromId: "user1", message: "", isOutgoing: false, isEdited: false, isForwarded: false },
+      ];
+
+      store.dispatch(addMessages({ userId, chatId: "chat1", messages }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.messages.chat1?.msg1).toBeDefined();
+      expect(state.messages.chat1?.msg2).toBeDefined();
+      expect(state.messages.chat1?.msg3).toBeDefined();
+      expect(state.messagesOrder.chat1).toEqual(["msg1", "msg2", "msg3"]);
+    });
+
+    it("addMessages: skips duplicates when adding to existing messages", () => {
+      store.dispatch(addMessage({ userId, message: { id: "msg1", chatId: "chat1", date: 1000, fromId: "user1", message: "", isOutgoing: false, isEdited: false, isForwarded: false } }));
+
+      const messages = [
+        { id: "msg1", chatId: "chat1", date: 1000, fromId: "user1", message: "", isOutgoing: false, isEdited: false, isForwarded: false },
+        { id: "msg2", chatId: "chat1", date: 2000, fromId: "user1", message: "", isOutgoing: false, isEdited: false, isForwarded: false },
+      ];
+
+      store.dispatch(addMessages({ userId, chatId: "chat1", messages }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.messagesOrder.chat1).toEqual(["msg1", "msg2"]);
+    });
+
+    it("updateMessage: updates fields of existing message", () => {
+      const message = { id: "msg1", chatId: "chat1", date: 1000, fromId: "user1", message: "Original", isOutgoing: false, isEdited: false, isForwarded: false };
+      store.dispatch(addMessage({ userId, message }));
+      store.dispatch(updateMessage({ userId, chatId: "chat1", messageId: "msg1", updates: { message: "Updated" } }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.messages.chat1?.msg1.message).toBe("Updated");
+      expect(state.messages.chat1?.msg1.fromId).toBe("user1");
+    });
+
+    it("updateMessage: does nothing if message does not exist", () => {
+      store.dispatch(updateMessage({ userId, chatId: "chat1", messageId: "nonexistent", updates: { message: "Test" } }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.messages.chat1?.nonexistent).toBeUndefined();
+    });
+
+    it("removeMessage: removes from messages and messagesOrder", () => {
+      store.dispatch(addMessage({ userId, message: { id: "msg1", chatId: "chat1", date: 1000, fromId: "user1", message: "", isOutgoing: false, isEdited: false, isForwarded: false } }));
+      store.dispatch(addMessage({ userId, message: { id: "msg2", chatId: "chat1", date: 2000, fromId: "user1", message: "", isOutgoing: false, isEdited: false, isForwarded: false } }));
+      store.dispatch(removeMessage({ userId, chatId: "chat1", messageId: "msg1" }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.messages.chat1?.msg1).toBeUndefined();
+      expect(state.messagesOrder.chat1).toEqual(["msg2"]);
+    });
+
+    it("clearMessages: clears all messages for a chat", () => {
+      store.dispatch(addMessage({ userId, message: { id: "msg1", chatId: "chat1", date: 1000, fromId: "user1", message: "", isOutgoing: false, isEdited: false, isForwarded: false } }));
+      store.dispatch(addMessage({ userId, message: { id: "msg2", chatId: "chat1", date: 2000, fromId: "user1", message: "", isOutgoing: false, isEdited: false, isForwarded: false } }));
+      store.dispatch(clearMessages({ userId, chatId: "chat1" }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.messages.chat1).toBeUndefined();
+      expect(state.messagesOrder.chat1).toBeUndefined();
+    });
+
+    it("deleteChatMessages: removes specific messages by ID", () => {
+      store.dispatch(addMessage({ userId, message: { id: "msg1", chatId: "chat1", date: 1000, fromId: "user1", message: "", isOutgoing: false, isEdited: false, isForwarded: false } }));
+      store.dispatch(addMessage({ userId, message: { id: "msg2", chatId: "chat1", date: 2000, fromId: "user1", message: "", isOutgoing: false, isEdited: false, isForwarded: false } }));
+      store.dispatch(addMessage({ userId, message: { id: "msg3", chatId: "chat1", date: 3000, fromId: "user1", message: "", isOutgoing: false, isEdited: false, isForwarded: false } }));
+
+      store.dispatch(deleteChatMessages({ userId, chatId: "chat1", messageIds: ["msg1", "msg3"] }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.messages.chat1?.msg1).toBeUndefined();
+      expect(state.messages.chat1?.msg2).toBeDefined();
+      expect(state.messages.chat1?.msg3).toBeUndefined();
+      expect(state.messagesOrder.chat1).toEqual(["msg2"]);
+    });
+
+    it("deleteChatMessages: cleans thread indices", () => {
+      store.dispatch(addMessage({ userId, message: { id: "msg1", chatId: "chat1", date: 1000, fromId: "user1", message: "", isOutgoing: false, isEdited: false, isForwarded: false } }));
+      store.dispatch(setThreadListedIds({ userId, chatId: "chat1", threadId: "0", listedIds: ["msg1"] }));
+      store.dispatch(deleteChatMessages({ userId, chatId: "chat1", messageIds: ["msg1"] }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.threadIndex.chat1?.["0"]?.listedIds).toEqual([]);
+    });
+
+    it("addChatMessagesById: adds messages, sorts by date, syncs main thread index", () => {
+      const messages = [
+        { id: "msg3", chatId: "chat1", date: 3000, fromId: "user1", message: "", isOutgoing: false, isEdited: false, isForwarded: false },
+        { id: "msg1", chatId: "chat1", date: 1000, fromId: "user1", message: "", isOutgoing: false, isEdited: false, isForwarded: false },
+        { id: "msg2", chatId: "chat1", date: 2000, fromId: "user1", message: "", isOutgoing: false, isEdited: false, isForwarded: false },
+      ];
+
+      store.dispatch(addChatMessagesById({ userId, chatId: "chat1", messages }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.messagesOrder.chat1).toEqual(["msg1", "msg2", "msg3"]);
+      expect(state.threadIndex.chat1?.["__main__"]?.listedIds).toEqual(["msg1", "msg2", "msg3"]);
+    });
+
+    it("addChatMessagesById: merges with existing messages", () => {
+      store.dispatch(addMessage({ userId, message: { id: "msg1", chatId: "chat1", date: 1000, fromId: "user1", message: "", isOutgoing: false, isEdited: false, isForwarded: false } }));
+
+      const messages = [
+        { id: "msg2", chatId: "chat1", date: 2000, fromId: "user1", message: "", isOutgoing: false, isEdited: false, isForwarded: false },
+        { id: "msg3", chatId: "chat1", date: 3000, fromId: "user1", message: "", isOutgoing: false, isEdited: false, isForwarded: false },
+      ];
+
+      store.dispatch(addChatMessagesById({ userId, chatId: "chat1", messages }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.messagesOrder.chat1).toEqual(["msg1", "msg2", "msg3"]);
+    });
+  });
+
+  describe("Thread Management", () => {
+    let store: ReturnType<typeof createStore>;
+
+    beforeEach(() => {
+      store = createStore();
+      store.dispatch(addChat({ userId, chat: { id: "chat1", type: "private" as const, unreadCount: 0, isPinned: false } }));
+    });
+
+    it("addThread: adds thread to threads[chatId][threadId]", () => {
+      const thread = {
+        id: "1",
+        chatId: "chat1",
+        title: "Thread 1",
+        messageCount: 0,
+        unreadCount: 0,
+        isPinned: false
+      };
+
+      store.dispatch(addThread({ userId, thread }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.threads.chat1?.["1"]).toEqual(thread);
+    });
+
+    it("updateThread: updates existing thread fields", () => {
+      const thread = {
+        id: "1",
+        chatId: "chat1",
+        title: "Thread 1",
+        messageCount: 0,
+        unreadCount: 0,
+        isPinned: false
+      };
+      store.dispatch(addThread({ userId, thread }));
+      store.dispatch(updateThread({ userId, chatId: "chat1", threadId: "1", updates: { title: "Updated Thread" } }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.threads.chat1?.["1"]?.title).toBe("Updated Thread");
+    });
+
+    it("updateThread: does nothing if thread does not exist", () => {
+      store.dispatch(updateThread({ userId, chatId: "chat1", threadId: "1", updates: { title: "Updated" } }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.threads.chat1?.["1"]).toBeUndefined();
+    });
+
+    it("setSelectedThread: sets selectedThreadId", () => {
+      store.dispatch(setSelectedChat({ userId, chatId: "chat1" }));
+      store.dispatch(setSelectedThread({ userId, threadId: "5" }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.selectedThreadId).toBe("5");
+    });
+  });
+
+  describe("Connection and Auth", () => {
+    let store: ReturnType<typeof createStore>;
+
+    beforeEach(() => {
+      store = createStore();
+    });
+
+    it("setConnectionStatus: updates status and clears error on non-error", () => {
+      store.dispatch(setConnectionError({ userId, error: "Previous error" }));
+      store.dispatch(setConnectionStatus({ userId, status: "connected" }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.connectionStatus).toBe("connected");
+      expect(state.connectionError).toBeNull();
+    });
+
+    it("setConnectionStatus: keeps error if status is error", () => {
+      store.dispatch(setConnectionError({ userId, error: "Connection failed" }));
+      store.dispatch(setConnectionStatus({ userId, status: "error" }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.connectionStatus).toBe("error");
+      expect(state.connectionError).toBe("Connection failed");
+    });
+
+    it("setConnectionError: sets error and status to error", () => {
+      store.dispatch(setConnectionStatus({ userId, status: "connected" }));
+      store.dispatch(setConnectionError({ userId, error: "Network failure" }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.connectionError).toBe("Network failure");
+      expect(state.connectionStatus).toBe("error");
+    });
+
+    it("setAuthStatus: updates auth status", () => {
+      store.dispatch(setAuthStatus({ userId, status: "authenticated" }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.authStatus).toBe("authenticated");
+    });
+
+    it("setAuthError: sets auth error and status to error", () => {
+      store.dispatch(setAuthStatus({ userId, status: "not_authenticated" }));
+      store.dispatch(setAuthError({ userId, error: "Invalid credentials" }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.authError).toBe("Invalid credentials");
+      expect(state.authStatus).toBe("error");
+    });
+
+    it("setPhoneNumber: updates phone number", () => {
+      store.dispatch(setPhoneNumber({ userId, phoneNumber: "+1234567890" }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.phoneNumber).toBe("+1234567890");
+    });
+
+    it("setSessionString: updates session string", () => {
+      store.dispatch(setSessionString({ userId, sessionString: "session123" }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.sessionString).toBe("session123");
+    });
+
+    it("setCurrentUser: updates current user", () => {
+      const user = { id: "u1", firstName: "John", lastName: "Doe", isBot: false };
+      store.dispatch(setCurrentUser({ userId, user }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.currentUser).toEqual(user);
+    });
+  });
+
+  describe("Sync Status", () => {
+    let store: ReturnType<typeof createStore>;
+
+    beforeEach(() => {
+      store = createStore();
+    });
+
+    it("setSyncStatus: updates isSyncing and isSynced", () => {
+      store.dispatch(setSyncStatus({ userId, isSyncing: true, isSynced: false }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.isSyncing).toBe(true);
+      expect(state.isSynced).toBe(false);
+    });
+
+    it("setSyncStatus: can update only isSyncing", () => {
+      store.dispatch(setSyncStatus({ userId, isSyncing: true }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.isSyncing).toBe(true);
+      expect(state.isSynced).toBe(false);
+    });
+
+    it("setSyncStatus: can update only isSynced", () => {
+      store.dispatch(setSyncStatus({ userId, isSynced: true }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.isSyncing).toBe(false);
+      expect(state.isSynced).toBe(true);
+    });
+  });
+
+  describe("Sequencing", () => {
+    let store: ReturnType<typeof createStore>;
+
+    beforeEach(() => {
+      store = createStore();
+    });
+
+    it("setCommonBoxState: sets seq/pts/qts/date", () => {
+      store.dispatch(setCommonBoxState({
+        userId,
+        commonBoxState: { seq: 100, pts: 200, qts: 50, date: 1234567890 }
+      }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.commonBoxState).toEqual({
+        seq: 100,
+        pts: 200,
+        qts: 50,
+        date: 1234567890,
+      });
+    });
+
+    it("setCommonBoxState: replaces entire state", () => {
+      store.dispatch(setCommonBoxState({
+        userId,
+        commonBoxState: { seq: 100, pts: 200, qts: 0, date: 0 }
+      }));
+      store.dispatch(setCommonBoxState({
+        userId,
+        commonBoxState: { seq: 150, pts: 250, qts: 50, date: 1234567890 }
+      }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.commonBoxState).toEqual({
+        seq: 150,
+        pts: 250,
+        qts: 50,
+        date: 1234567890,
+      });
+    });
+
+    it("setChannelPts: sets per-channel pts", () => {
+      store.dispatch(setChannelPts({ userId, channelId: "channel1", pts: 150 }));
+      store.dispatch(setChannelPts({ userId, channelId: "channel2", pts: 250 }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.channelPtsById.channel1).toBe(150);
+      expect(state.channelPtsById.channel2).toBe(250);
+    });
+  });
+
+  describe("Reset Functions", () => {
+    let store: ReturnType<typeof createStore>;
+
+    beforeEach(() => {
+      store = createStore();
+      store.dispatch(addChat({ userId, chat: { id: "chat1", type: "private" as const, unreadCount: 0, isPinned: false } }));
+      store.dispatch(addMessage({ userId, message: { id: "msg1", chatId: "chat1", date: 1000, fromId: "user1", message: "", isOutgoing: false, isEdited: false, isForwarded: false } }));
+      store.dispatch(setConnectionStatus({ userId, status: "connected" }));
+      store.dispatch(setAuthStatus({ userId, status: "authenticated" }));
+    });
+
+    it("resetTelegramForUser: resets user state to initial", () => {
+      store.dispatch(resetTelegramForUser({ userId }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.chats).toEqual({});
+      expect(state.chatsOrder).toEqual([]);
+      expect(state.messages).toEqual({});
+      expect(state.messagesOrder).toEqual({});
+      expect(state.connectionStatus).toBe("disconnected");
+      expect(state.authStatus).toBe("not_authenticated");
+    });
+
+    it("resetChats: clears chats and order", () => {
+      store.dispatch(resetChats({ userId }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.chats).toEqual({});
+      expect(state.chatsOrder).toEqual([]);
+      expect(state.messages).toBeDefined();
+    });
+
+    it("resetMessages: clears all messages", () => {
+      store.dispatch(resetMessages({ userId }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.messages).toEqual({});
+      expect(state.messagesOrder).toEqual({});
+      expect(state.chats).toBeDefined();
+    });
+  });
+
+  describe("Thread Indexing", () => {
+    let store: ReturnType<typeof createStore>;
+
+    beforeEach(() => {
+      store = createStore();
+      store.dispatch(addChat({ userId, chat: { id: "chat1", type: "private" as const, unreadCount: 0, isPinned: false } }));
+    });
+
+    it("setViewportIds: sets viewport IDs for chat+thread", () => {
+      store.dispatch(setViewportIds({ userId, chatId: "chat1", threadId: "0", viewportIds: ["msg1", "msg2", "msg3"] }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.threadIndex.chat1?.["0"]?.viewportIds).toEqual(["msg1", "msg2", "msg3"]);
+    });
+
+    it("addOutlyingList: adds outlying list", () => {
+      const ids = ["msg1", "msg2"];
+      store.dispatch(addOutlyingList({ userId, chatId: "chat1", threadId: "0", ids }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.threadIndex.chat1?.["0"]?.outlyingLists).toContainEqual(ids);
+    });
+
+    it("addOutlyingList: appends to existing outlying lists", () => {
+      const ids1 = ["msg1", "msg2"];
+      const ids2 = ["msg3", "msg4"];
+
+      store.dispatch(addOutlyingList({ userId, chatId: "chat1", threadId: "0", ids: ids1 }));
+      store.dispatch(addOutlyingList({ userId, chatId: "chat1", threadId: "0", ids: ids2 }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.threadIndex.chat1?.["0"]?.outlyingLists).toHaveLength(2);
+    });
+
+    it("setThreadListedIds: sets listed IDs for a thread", () => {
+      store.dispatch(setThreadListedIds({ userId, chatId: "chat1", threadId: "0", listedIds: ["msg1", "msg2", "msg3"] }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.threadIndex.chat1?.["0"]?.listedIds).toEqual(["msg1", "msg2", "msg3"]);
+    });
+  });
+
+  describe("User Management", () => {
+    let store: ReturnType<typeof createStore>;
+
+    beforeEach(() => {
+      store = createStore();
+    });
+
+    it("setUsers: replaces all users", () => {
+      const users = {
+        user1: { id: "user1", firstName: "Alice", isBot: false },
+        user2: { id: "user2", firstName: "Bob", isBot: false },
+      };
+
+      store.dispatch(setUsers({ userId, users }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.users).toEqual(users);
+    });
+
+    it("addUsers: merges users with existing", () => {
+      store.dispatch(setUsers({ userId, users: { user1: { id: "user1", firstName: "Alice", isBot: false } } }));
+      store.dispatch(addUsers({ userId, users: { user2: { id: "user2", firstName: "Bob", isBot: false } } }));
+
+      const state = store.getState().telegram.byUser[userId];
+      expect(state.users.user1).toBeDefined();
+      expect(state.users.user2).toBeDefined();
+    });
+  });
+
+  describe("Multiple Users", () => {
+    let store: ReturnType<typeof createStore>;
+
+    beforeEach(() => {
+      store = createStore();
+    });
+
+    it("maintains separate state for different users", () => {
+      const userId1 = "u1";
+      const userId2 = "u2";
+
+      store.dispatch(addChat({ userId: userId1, chat: { id: "chat1", type: "private" as const, unreadCount: 0, isPinned: false } }));
+      store.dispatch(addChat({ userId: userId2, chat: { id: "chat2", type: "group" as const, unreadCount: 0, isPinned: false } }));
+
+      const state1 = store.getState().telegram.byUser[userId1];
+      const state2 = store.getState().telegram.byUser[userId2];
+
+      expect(state1.chats.chat1).toBeDefined();
+      expect(state1.chats.chat2).toBeUndefined();
+      expect(state2.chats.chat2).toBeDefined();
+      expect(state2.chats.chat1).toBeUndefined();
+    });
+
+    it("resets only specified user state", () => {
+      const userId1 = "u1";
+      const userId2 = "u2";
+
+      store.dispatch(addChat({ userId: userId1, chat: { id: "chat1", type: "private" as const, unreadCount: 0, isPinned: false } }));
+      store.dispatch(addChat({ userId: userId2, chat: { id: "chat2", type: "group" as const, unreadCount: 0, isPinned: false } }));
+      store.dispatch(resetTelegramForUser({ userId: userId1 }));
+
+      const state1 = store.getState().telegram.byUser[userId1];
+      const state2 = store.getState().telegram.byUser[userId2];
+
+      expect(state1.chats).toEqual({});
+      expect(state2.chats.chat2).toBeDefined();
+    });
+  });
+});
diff --git a/src/store/telegram/reducers.ts b/src/store/telegram/reducers.ts
index 328b4a2eb..ad88fd9fd 100644
--- a/src/store/telegram/reducers.ts
+++ b/src/store/telegram/reducers.ts
@@ -17,7 +17,20 @@ function ensureUser(
   userId: string,
 ): TelegramState {
   if (!state.byUser[userId]) {
-    state.byUser[userId] = { ...initialState };
+    // Create a deep copy of nested objects to avoid sharing references with initialState
+    state.byUser[userId] = {
+      ...initialState,
+      chats: {},
+      chatsOrder: [],
+      messages: {},
+      messagesOrder: {},
+      threads: {},
+      threadsOrder: {},
+      threadIndex: {},
+      users: {},
+      channelPtsById: {},
+      commonBoxState: { ...initialState.commonBoxState },
+    };
   }
   return state.byUser[userId];
 }
@@ -41,6 +54,91 @@ function ensureThreadIndex(
 }
 
 export const reducers = {
+  // ---------------------------------------------------------------------------
+  // Sync state
+  // ---------------------------------------------------------------------------
+
+  setSyncStatus: (
+    state: TelegramRootState,
+    action: PayloadAction<{
+      userId: string;
+      isSyncing?: boolean;
+      isSynced?: boolean;
+    }>,
+  ) => {
+    const u = ensureUser(state, action.payload.userId);
+    if (action.payload.isSyncing !== undefined)
+      u.isSyncing = action.payload.isSyncing;
+    if (action.payload.isSynced !== undefined)
+      u.isSynced = action.payload.isSynced;
+  },
+
+  // ---------------------------------------------------------------------------
+  // Users map
+  // ---------------------------------------------------------------------------
+
+  setUsers: (
+    state: TelegramRootState,
+    action: PayloadAction<{
+      userId: string;
+      users: Record<string, TelegramUser>;
+    }>,
+  ) => {
+    ensureUser(state, action.payload.userId).users = action.payload.users;
+  },
+
+  addUsers: (
+    state: TelegramRootState,
+    action: PayloadAction<{
+      userId: string;
+      users: Record<string, TelegramUser>;
+    }>,
+  ) => {
+    const u = ensureUser(state, action.payload.userId);
+    Object.assign(u.users, action.payload.users);
+  },
+
+  // ---------------------------------------------------------------------------
+  // Chats — replace (first batch) and append
+  // ---------------------------------------------------------------------------
+
+  replaceChats: (
+    state: TelegramRootState,
+    action: PayloadAction<{
+      userId: string;
+      chats: Record<string, TelegramChat>;
+      chatsOrder: string[];
+    }>,
+  ) => {
+    const u = ensureUser(state, action.payload.userId);
+    u.chats = action.payload.chats;
+    u.chatsOrder = action.payload.chatsOrder;
+  },
+
+  addChats: (
+    state: TelegramRootState,
+    action: PayloadAction<{
+      userId: string;
+      chats: Record<string, TelegramChat>;
+      appendOrder: string[];
+    }>,
+  ) => {
+    const u = ensureUser(state, action.payload.userId);
+    Object.assign(u.chats, action.payload.chats);
+    // Append new IDs that aren't already in order
+    const existing = new Set(u.chatsOrder);
+    for (const id of action.payload.appendOrder) {
+      if (!existing.has(id)) {
+        u.chatsOrder.push(id);
+        existing.add(id);
+      }
+    }
+  },
+
+  // ---------------------------------------------------------------------------
+  // Connection / Auth
+  // ---------------------------------------------------------------------------
+
   setConnectionStatus: (
     state: TelegramRootState,
     action: PayloadAction<{ userId: string; status: TelegramConnectionStatus }>,
diff --git a/src/store/telegram/types.ts b/src/store/telegram/types.ts
index 275ad6a13..edb36ed00 100644
--- a/src/store/telegram/types.ts
+++ b/src/store/telegram/types.ts
@@ -101,9 +101,16 @@ export interface TelegramState {
   phoneNumber: string | null;
   sessionString: string | null;
 
+  // Sync state
+  isSyncing: boolean;
+  isSynced: boolean;
+
   // User data
   currentUser: TelegramUser | null;
 
+  // Users map (all known users from chats/messages)
+  users: Record<string, TelegramUser>;
+
   // Chats
   chats: Record<string, TelegramChat>;
   chatsOrder: string[]; // Ordered list of chat IDs
@@ -169,8 +176,13 @@ export const initialState: TelegramState = {
   phoneNumber: null,
   sessionString: null,
 
+  // Sync
+  isSyncing: false,
+  isSynced: false,
+
   // User
   currentUser: null,
+  users: {},
 
   // Chats
   chats: {},
diff --git a/src/store/telegramSelectors.test.ts b/src/store/telegramSelectors.test.ts
new file mode 100644
index 000000000..a73766537
--- /dev/null
+++ b/src/store/telegramSelectors.test.ts
@@ -0,0 +1,550 @@
+import { describe, it, expect } from "vitest";
+import {
+  selectTelegramUserState,
+  selectIsConnected,
+  selectIsAuthenticated,
+  selectCurrentUser,
+  selectOrderedChats,
+  selectChatMessages,
+  selectTotalUnreadCount,
+  selectPinnedChats,
+  selectChatMessageById,
+  selectTelegramReady,
+  selectConnectionStatus,
+  selectAuthStatus,
+  selectIsInitialized,
+  selectSelectedChat,
+  selectFilteredChats,
+  selectChatLatestMessage,
+} from "./telegramSelectors";
+import type { TelegramState, TelegramChat, TelegramMessage } from "./telegram/types";
+import { initialState } from "./telegram/types";
+import type { RootState } from "./index";
+
+/**
+ * Helper to build a mock RootState with customizable telegram state
+ */
+function mockState(
+  telegramOverrides: Partial<TelegramState> = {},
+  userId = "u1"
+): RootState {
+  return {
+    auth: { token: "tok", isOnboardedByUser: {} },
+    socket: { byUser: {} },
+    user: {
+      user: { _id: userId, telegramId: 1 } as any,
+      isLoading: false,
+      error: null,
+    },
+    telegram: {
+      byUser: {
+        [userId]: { ...initialState, ...telegramOverrides },
+      },
+    },
+  } as any;
+}
+
+describe("telegramSelectors", () => {
+  describe("selectTelegramUserState", () => {
+    it("returns user state when user exists", () => {
+      const state = mockState({ connectionStatus: "connected" });
+      const result = selectTelegramUserState(state);
+      expect(result.connectionStatus).toBe("connected");
+    });
+
+    it("returns default initialState when user not found", () => {
+      const state = mockState({}, "u1");
+      // Clear the user from state
+      state.user.user = null;
+      const result = selectTelegramUserState(state);
+      expect(result).toEqual(initialState);
+    });
+
+    it("returns default initialState when userId has no telegram state", () => {
+      const state = mockState({}, "u1");
+      state.telegram.byUser = {}; // Empty byUser map
+      const result = selectTelegramUserState(state);
+      expect(result).toEqual(initialState);
+    });
+  });
+
+  describe("selectIsConnected", () => {
+    it("returns true when connectionStatus is connected", () => {
+      const state = mockState({ connectionStatus: "connected" });
+      expect(selectIsConnected(state)).toBe(true);
+    });
+
+    it("returns false when connectionStatus is disconnected", () => {
+      const state = mockState({ connectionStatus: "disconnected" });
+      expect(selectIsConnected(state)).toBe(false);
+    });
+
+    it("returns false when connectionStatus is connecting", () => {
+      const state = mockState({ connectionStatus: "connecting" });
+      expect(selectIsConnected(state)).toBe(false);
+    });
+
+    it("returns false when connectionStatus is error", () => {
+      const state = mockState({ connectionStatus: "error" });
+      expect(selectIsConnected(state)).toBe(false);
+    });
+  });
+
+  describe("selectIsAuthenticated", () => {
+    it("returns true when authStatus is authenticated", () => {
+      const state = mockState({ authStatus: "authenticated" });
+      expect(selectIsAuthenticated(state)).toBe(true);
+    });
+
+    it("returns false when authStatus is not_authenticated", () => {
+      const state = mockState({ authStatus: "not_authenticated" });
+      expect(selectIsAuthenticated(state)).toBe(false);
+    });
+
+    it("returns false when authStatus is authenticating", () => {
+      const state = mockState({ authStatus: "authenticating" });
+      expect(selectIsAuthenticated(state)).toBe(false);
+    });
+
+    it("returns false when authStatus is error", () => {
+      const state = mockState({ authStatus: "error" });
+      expect(selectIsAuthenticated(state)).toBe(false);
+    });
+  });
+
+  describe("selectCurrentUser", () => {
+    it("returns currentUser from state", () => {
+      const currentUser = {
+        id: "123",
+        firstName: "Alice",
+        lastName: "Smith",
+        username: "alice",
+        isBot: false,
+      };
+      const state = mockState({ currentUser });
+      expect(selectCurrentUser(state)).toEqual(currentUser);
+    });
+
+    it("returns null when currentUser is not set", () => {
+      const state = mockState({ currentUser: null });
+      expect(selectCurrentUser(state)).toBeNull();
+    });
+  });
+
+  describe("selectOrderedChats", () => {
+    it("returns chats in chatsOrder sequence", () => {
+      const chat1: TelegramChat = {
+        id: "c1",
+        title: "Chat 1",
+        type: "private",
+        unreadCount: 0,
+        isPinned: false,
+      };
+      const chat2: TelegramChat = {
+        id: "c2",
+        title: "Chat 2",
+        type: "group",
+        unreadCount: 5,
+        isPinned: true,
+      };
+      const state = mockState({
+        chats: { c1: chat1, c2: chat2 },
+        chatsOrder: ["c2", "c1"],
+      });
+      const result = selectOrderedChats(state);
+      expect(result).toEqual([chat2, chat1]);
+    });
+
+    it("skips missing chats that are in chatsOrder", () => {
+      const chat1: TelegramChat = {
+        id: "c1",
+        title: "Chat 1",
+        type: "private",
+        unreadCount: 0,
+        isPinned: false,
+      };
+      const state = mockState({
+        chats: { c1: chat1 },
+        chatsOrder: ["c1", "c2", "c3"], // c2, c3 missing
+      });
+      const result = selectOrderedChats(state);
+      expect(result).toEqual([chat1]);
+    });
+
+    it("returns empty array when no chats", () => {
+      const state = mockState({ chats: {}, chatsOrder: [] });
+      const result = selectOrderedChats(state);
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe("selectChatMessages", () => {
+    it("returns ordered messages for a chat", () => {
+      const msg1: TelegramMessage = {
+        id: "m1",
+        chatId: "c1",
+        date: 1000,
+        message: "Hello",
+        isOutgoing: true,
+        isEdited: false,
+        isForwarded: false,
+      };
+      const msg2: TelegramMessage = {
+        id: "m2",
+        chatId: "c1",
+        date: 2000,
+        message: "World",
+        isOutgoing: false,
+        isEdited: false,
+        isForwarded: false,
+      };
+      const state = mockState({
+        messages: {
+          c1: { m1: msg1, m2: msg2 },
+        },
+        messagesOrder: {
+          c1: ["m1", "m2"],
+        },
+      });
+      const result = selectChatMessages(state, "c1");
+      expect(result).toEqual([msg1, msg2]);
+    });
+
+    it("returns empty array when chat has no messages", () => {
+      const state = mockState({
+        messages: {},
+        messagesOrder: {},
+      });
+      const result = selectChatMessages(state, "c1");
+      expect(result).toEqual([]);
+    });
+
+    it("skips missing messages in messagesOrder", () => {
+      const msg1: TelegramMessage = {
+        id: "m1",
+        chatId: "c1",
+        date: 1000,
+        message: "Hello",
+        isOutgoing: true,
+        isEdited: false,
+        isForwarded: false,
+      };
+      const state = mockState({
+        messages: {
+          c1: { m1: msg1 },
+        },
+        messagesOrder: {
+          c1: ["m1", "m2"], // m2 missing
+        },
+      });
+      const result = selectChatMessages(state, "c1");
+      expect(result).toEqual([msg1]);
+    });
+  });
+
+  describe("selectTotalUnreadCount", () => {
+    it("sums unreadCount across all ordered chats", () => {
+      const chat1: TelegramChat = {
+        id: "c1",
+        title: "Chat 1",
+        type: "private",
+        unreadCount: 5,
+        isPinned: false,
+      };
+      const chat2: TelegramChat = {
+        id: "c2",
+        title: "Chat 2",
+        type: "group",
+        unreadCount: 10,
+        isPinned: false,
+      };
+      const chat3: TelegramChat = {
+        id: "c3",
+        title: "Chat 3",
+        type: "channel",
+        unreadCount: 0,
+        isPinned: true,
+      };
+      const state = mockState({
+        chats: { c1: chat1, c2: chat2, c3: chat3 },
+        chatsOrder: ["c1", "c2", "c3"],
+      });
+      expect(selectTotalUnreadCount(state)).toBe(15);
+    });
+
+    it("returns 0 when no chats have unread messages", () => {
+      const chat1: TelegramChat = {
+        id: "c1",
+        title: "Chat 1",
+        type: "private",
+        unreadCount: 0,
+        isPinned: false,
+      };
+      const state = mockState({
+        chats: { c1: chat1 },
+        chatsOrder: ["c1"],
+      });
+      expect(selectTotalUnreadCount(state)).toBe(0);
+    });
+
+    it("returns 0 when no chats", () => {
+      const state = mockState({
+        chats: {},
+        chatsOrder: [],
+      });
+      expect(selectTotalUnreadCount(state)).toBe(0);
+    });
+  });
+
+  describe("selectPinnedChats", () => {
+    it("filters to only pinned chats", () => {
+      const chat1: TelegramChat = {
+        id: "c1",
+        title: "Chat 1",
+        type: "private",
+        unreadCount: 0,
+        isPinned: false,
+      };
+      const chat2: TelegramChat = {
+        id: "c2",
+        title: "Chat 2",
+        type: "group",
+        unreadCount: 5,
+        isPinned: true,
+      };
+      const chat3: TelegramChat = {
+        id: "c3",
+        title: "Chat 3",
+        type: "channel",
+        unreadCount: 0,
+        isPinned: true,
+      };
+      const state = mockState({
+        chats: { c1: chat1, c2: chat2, c3: chat3 },
+        chatsOrder: ["c1", "c2", "c3"],
+      });
+      const result = selectPinnedChats(state);
+      expect(result).toEqual([chat2, chat3]);
+    });
+
+    it("returns empty array when no pinned chats", () => {
+      const chat1: TelegramChat = {
+        id: "c1",
+        title: "Chat 1",
+        type: "private",
+        unreadCount: 0,
+        isPinned: false,
+      };
+      const state = mockState({
+        chats: { c1: chat1 },
+        chatsOrder: ["c1"],
+      });
+      const result = selectPinnedChats(state);
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe("selectChatMessageById", () => {
+    it("performs O(1) lookup by chatId and messageId", () => {
+      const msg1: TelegramMessage = {
+        id: "m1",
+        chatId: "c1",
+        date: 1000,
+        message: "Hello",
+        isOutgoing: true,
+        isEdited: false,
+        isForwarded: false,
+      };
+      const state = mockState({
+        messages: {
+          c1: { m1: msg1 },
+        },
+      });
+      const result = selectChatMessageById(state, "c1", "m1");
+      expect(result).toEqual(msg1);
+    });
+
+    it("returns undefined when message not found", () => {
+      const state = mockState({
+        messages: {
+          c1: {},
+        },
+      });
+      const result = selectChatMessageById(state, "c1", "m1");
+      expect(result).toBeUndefined();
+    });
+
+    it("returns undefined when chat not found", () => {
+      const state = mockState({
+        messages: {},
+      });
+      const result = selectChatMessageById(state, "c1", "m1");
+      expect(result).toBeUndefined();
+    });
+  });
+
+  describe("selectTelegramReady", () => {
+    it("returns true when connected, authenticated, and initialized", () => {
+      const state = mockState({
+        connectionStatus: "connected",
+        authStatus: "authenticated",
+        isInitialized: true,
+      });
+      expect(selectTelegramReady(state)).toBe(true);
+    });
+
+    it("returns false when not connected", () => {
+      const state = mockState({
+        connectionStatus: "disconnected",
+        authStatus: "authenticated",
+        isInitialized: true,
+      });
+      expect(selectTelegramReady(state)).toBe(false);
+    });
+
+    it("returns false when not authenticated", () => {
+      const state = mockState({
+        connectionStatus: "connected",
+        authStatus: "not_authenticated",
+        isInitialized: true,
+      });
+      expect(selectTelegramReady(state)).toBe(false);
+    });
+
+    it("returns false when not initialized", () => {
+      const state = mockState({
+        connectionStatus: "connected",
+        authStatus: "authenticated",
+        isInitialized: false,
+      });
+      expect(selectTelegramReady(state)).toBe(false);
+    });
+
+    it("returns false when none are ready", () => {
+      const state = mockState({
+        connectionStatus: "disconnected",
+        authStatus: "not_authenticated",
+        isInitialized: false,
+      });
+      expect(selectTelegramReady(state)).toBe(false);
+    });
+  });
+
+  describe("additional selectors", () => {
+    it("selectConnectionStatus returns connection status", () => {
+      const state = mockState({ connectionStatus: "connecting" });
+      expect(selectConnectionStatus(state)).toBe("connecting");
+    });
+
+    it("selectAuthStatus returns auth status", () => {
+      const state = mockState({ authStatus: "authenticating" });
+      expect(selectAuthStatus(state)).toBe("authenticating");
+    });
+
+    it("selectIsInitialized returns initialization status", () => {
+      const state = mockState({ isInitialized: true });
+      expect(selectIsInitialized(state)).toBe(true);
+    });
+
+    it("selectSelectedChat returns selected chat", () => {
+      const chat1: TelegramChat = {
+        id: "c1",
+        title: "Chat 1",
+        type: "private",
+        unreadCount: 0,
+        isPinned: false,
+      };
+      const state = mockState({
+        chats: { c1: chat1 },
+        selectedChatId: "c1",
+      });
+      expect(selectSelectedChat(state)).toEqual(chat1);
+    });
+
+    it("selectSelectedChat returns null when no chat selected", () => {
+      const state = mockState({ selectedChatId: null });
+      expect(selectSelectedChat(state)).toBeNull();
+    });
+
+    it("selectFilteredChats filters by filteredChatIds", () => {
+      const chat1: TelegramChat = {
+        id: "c1",
+        title: "Chat 1",
+        type: "private",
+        unreadCount: 0,
+        isPinned: false,
+      };
+      const chat2: TelegramChat = {
+        id: "c2",
+        title: "Chat 2",
+        type: "group",
+        unreadCount: 5,
+        isPinned: true,
+      };
+      const state = mockState({
+        chats: { c1: chat1, c2: chat2 },
+        chatsOrder: ["c1", "c2"],
+        filteredChatIds: ["c2"],
+      });
+      const result = selectFilteredChats(state);
+      expect(result).toEqual([chat2]);
+    });
+
+    it("selectFilteredChats returns all chats when no filter", () => {
+      const chat1: TelegramChat = {
+        id: "c1",
+        title: "Chat 1",
+        type: "private",
+        unreadCount: 0,
+        isPinned: false,
+      };
+      const state = mockState({
+        chats: { c1: chat1 },
+        chatsOrder: ["c1"],
+        filteredChatIds: null,
+      });
+      const result = selectFilteredChats(state);
+      expect(result).toEqual([chat1]);
+    });
+
+    it("selectChatLatestMessage returns last message", () => {
+      const msg1: TelegramMessage = {
+        id: "m1",
+        chatId: "c1",
+        date: 1000,
+        message: "Hello",
+        isOutgoing: true,
+        isEdited: false,
+        isForwarded: false,
+      };
+      const msg2: TelegramMessage = {
+        id: "m2",
+        chatId: "c1",
+        date: 2000,
+        message: "World",
+        isOutgoing: false,
+        isEdited: false,
+        isForwarded: false,
+      };
+      const state = mockState({
+        messages: {
+          c1: { m1: msg1, m2: msg2 },
+        },
+        messagesOrder: {
+          c1: ["m1", "m2"],
+        },
+      });
+      const result = selectChatLatestMessage(state, "c1");
+      expect(result).toEqual(msg2);
+    });
+
+    it("selectChatLatestMessage returns null when no messages", () => {
+      const state = mockState({
+        messages: {},
+        messagesOrder: {},
+      });
+      const result = selectChatLatestMessage(state, "c1");
+      expect(result).toBeNull();
+    });
+  });
+});
diff --git a/src/utils/deeplink.ts b/src/utils/deeplink.ts
index 441d848a8..377805831 100644
--- a/src/utils/deeplink.ts
+++ b/src/utils/deeplink.ts
@@ -21,35 +21,3 @@ export const buildDesktopDeeplink = (token: string): string => {
   const encoded = encodeURIComponent(token);
   return `${DESKTOP_SCHEME}://auth?token=${encoded}`;
 };
-
-/**
- * Call the backend to complete the web login and obtain a short-lived token
- * that can be handed off to the desktop app via deeplink.
- *
- * This expects a backend endpoint at POST /api/auth/web-complete that
- * validates the current web session and returns `{ loginToken: string }`.
- */
-export const completeWebLoginAndOpenDesktop = async (
-  context: WebLoginContext,
-): Promise<void> => {
-  const response = await fetch("/api/auth/web-complete", {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-    },
-    body: JSON.stringify(context),
-    credentials: "include",
-  });
-
-  if (!response.ok) {
-    throw new Error("Failed to complete web login for desktop handoff");
-  }
-
-  const data = (await response.json()) as { loginToken?: string };
-  if (!data.loginToken) {
-    throw new Error("Backend response did not include a loginToken");
-  }
-
-  const deeplink = buildDesktopDeeplink(data.loginToken);
-  window.location.href = deeplink;
-};
diff --git a/src/utils/desktopDeepLinkListener.ts b/src/utils/desktopDeepLinkListener.ts
index 94d092925..8cedec5d3 100644
--- a/src/utils/desktopDeepLinkListener.ts
+++ b/src/utils/desktopDeepLinkListener.ts
@@ -1,8 +1,8 @@
 import { getCurrent, onOpenUrl } from "@tauri-apps/plugin-deep-link";
 import { invoke, isTauri as coreIsTauri } from "@tauri-apps/api/core";
-import { BACKEND_URL } from "./config";
 import { store } from "../store";
 import { setToken } from "../store/authSlice";
+import { consumeLoginToken } from "../services/api/authApi";
 
 /**
  * Handle a list of deep link URLs delivered by the Tauri deep-link plugin.
@@ -32,7 +32,7 @@ const handleDeepLinkUrls = async (urls: string[] | null | undefined) => {
       return;
     }
 
-    console.log("[DeepLink] Received token");
+    console.log("[DeepLink] Received token", token);
 
     try {
       // Bring app window to foreground so macOS users actually see completion.
@@ -43,19 +43,8 @@ const handleDeepLinkUrls = async (urls: string[] | null | undefined) => {
       console.warn("[DeepLink] Failed to show window:", err);
     }
 
-    // Use Tauri invoke to call Rust backend (bypasses CORS)
-    const data = await invoke<{
-      sessionToken?: string;
-    }>("exchange_token", { backendUrl: BACKEND_URL, token });
-
-    const sessionToken = data.sessionToken;
-    if (!sessionToken) {
-      console.warn("[DeepLink] Token exchange did not return a sessionToken");
-      return;
-    }
-
-    // Store session token in store
-    store.dispatch(setToken(sessionToken));
+    const jwtToken = await consumeLoginToken(token);
+    store.dispatch(setToken(jwtToken));
 
     // Navigate to post-login flow. We use HashRouter, so update the hash route.
     window.location.hash = "/onboarding";
diff --git a/vitest.config.ts b/vitest.config.ts
new file mode 100644
index 000000000..6dd070ab5
--- /dev/null
+++ b/vitest.config.ts
@@ -0,0 +1,43 @@
+import { defineConfig } from "vitest/config";
+import { nodePolyfills } from "vite-plugin-node-polyfills";
+
+export default defineConfig({
+  plugins: [
+    nodePolyfills({
+      include: ["buffer", "process", "util", "os", "crypto", "stream"],
+      globals: {
+        Buffer: true,
+        process: true,
+        global: true,
+      },
+    }),
+  ],
+  resolve: {
+    alias: {
+      buffer: "buffer",
+      process: "process/browser",
+      util: "util",
+      os: "os-browserify/browser",
+    },
+  },
+  test: {
+    globals: true,
+    environment: "node",
+    mockReset: true,
+    restoreMocks: true,
+    setupFiles: ["src/__tests__/setup.ts"],
+    include: ["src/**/*.test.ts"],
+    hookTimeout: 30000,
+    testTimeout: 30000,
+    coverage: {
+      provider: "v8",
+      include: [
+        "src/lib/mcp/**",
+        "src/store/telegram/**",
+        "src/services/updateManager.ts",
+        "src/services/messageLoader.ts",
+      ],
+      reporter: ["text", "html"],
+    },
+  },
+});
diff --git a/yarn.lock b/yarn.lock
index 85b1130f8..6abcf1403 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -21,7 +21,7 @@
   resolved "https://registry.npmjs.org/@babel/compat-data/-/compat-data-7.28.6.tgz"
   integrity sha512-2lfu57JtzctfIrcGMz992hyLlByuzgIk58+hhGCxjKZ3rWI82NnVLjXcaTqkI2NvlcvOskZaiZ5kjUALo3Lpxg==
 
-"@babel/core@^7.28.0":
+"@babel/core@^7.0.0", "@babel/core@^7.0.0-0", "@babel/core@^7.28.0":
   version "7.28.6"
   resolved "https://registry.npmjs.org/@babel/core/-/core-7.28.6.tgz"
   integrity sha512-H3mcG6ZDLTlYfaSNi0iOKkigqMFvkTKlGUYlD8GW7nNOYRrevuA46iTypPyv+06V3fEmvvazfntkBU34L0azAw==
@@ -114,7 +114,7 @@
     "@babel/template" "^7.28.6"
     "@babel/types" "^7.28.6"
 
-"@babel/parser@^7.1.0", "@babel/parser@^7.20.7", "@babel/parser@^7.28.6":
+"@babel/parser@^7.1.0", "@babel/parser@^7.20.7", "@babel/parser@^7.28.5", "@babel/parser@^7.28.6":
   version "7.28.6"
   resolved "https://registry.npmjs.org/@babel/parser/-/parser-7.28.6.tgz"
   integrity sha512-TeR9zWR18BvbfPmGbLampPMW+uW1NZnJlRuuHso8i87QZNq2JRF9i6RgxRqtEq+wQGsS19NNTWr2duhnE49mfQ==
@@ -157,7 +157,7 @@
     "@babel/types" "^7.28.6"
     debug "^4.3.1"
 
-"@babel/types@^7.0.0", "@babel/types@^7.20.7", "@babel/types@^7.28.2", "@babel/types@^7.28.6":
+"@babel/types@^7.0.0", "@babel/types@^7.20.7", "@babel/types@^7.28.2", "@babel/types@^7.28.5", "@babel/types@^7.28.6":
   version "7.28.6"
   resolved "https://registry.npmjs.org/@babel/types/-/types-7.28.6.tgz"
   integrity sha512-0ZrskXVEHSWIqZM/sQZ4EV3jZJXRkio/WCxaqKZP1g//CEWEPSfeZFcms4XeKBCHU0ZKnIkdJeU/kF+eRp5lBg==
@@ -165,6 +165,11 @@
     "@babel/helper-string-parser" "^7.27.1"
     "@babel/helper-validator-identifier" "^7.28.5"
 
+"@bcoe/v8-coverage@^1.0.2":
+  version "1.0.2"
+  resolved "https://registry.npmjs.org/@bcoe/v8-coverage/-/v8-coverage-1.0.2.tgz"
+  integrity sha512-6zABk/ECA/QYSCQ1NGiVwwbQerUCZ+TQbp64Q3AgmfNvurHH0j8TtXa1qbShXA6qqkpAj4V5W8pP6mLe1mcMqA==
+
 "@cryptography/aes@^0.1.1":
   version "0.1.1"
   resolved "https://registry.npmjs.org/@cryptography/aes/-/aes-0.1.1.tgz"
@@ -172,22 +177,22 @@
 
 "@esbuild/aix-ppc64@0.27.2":
   version "0.27.2"
-  resolved "https://registry.yarnpkg.com/@esbuild/aix-ppc64/-/aix-ppc64-0.27.2.tgz#521cbd968dcf362094034947f76fa1b18d2d403c"
+  resolved "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.27.2.tgz"
   integrity sha512-GZMB+a0mOMZs4MpDbj8RJp4cw+w1WV5NYD6xzgvzUJ5Ek2jerwfO2eADyI6ExDSUED+1X8aMbegahsJi+8mgpw==
 
-"@esbuild/android-arm64@0.27.2":
-  version "0.27.2"
-  resolved "https://registry.yarnpkg.com/@esbuild/android-arm64/-/android-arm64-0.27.2.tgz#61ea550962d8aa12a9b33194394e007657a6df57"
-  integrity sha512-pvz8ZZ7ot/RBphf8fv60ljmaoydPU12VuXHImtAs0XhLLw+EXBi2BLe3OYSBslR4rryHvweW5gmkKFwTiFy6KA==
-
 "@esbuild/android-arm@0.27.2":
   version "0.27.2"
-  resolved "https://registry.yarnpkg.com/@esbuild/android-arm/-/android-arm-0.27.2.tgz#554887821e009dd6d853f972fde6c5143f1de142"
+  resolved "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.27.2.tgz"
   integrity sha512-DVNI8jlPa7Ujbr1yjU2PfUSRtAUZPG9I1RwW4F4xFB1Imiu2on0ADiI/c3td+KmDtVKNbi+nffGDQMfcIMkwIA==
 
+"@esbuild/android-arm64@0.27.2":
+  version "0.27.2"
+  resolved "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.27.2.tgz"
+  integrity sha512-pvz8ZZ7ot/RBphf8fv60ljmaoydPU12VuXHImtAs0XhLLw+EXBi2BLe3OYSBslR4rryHvweW5gmkKFwTiFy6KA==
+
 "@esbuild/android-x64@0.27.2":
   version "0.27.2"
-  resolved "https://registry.yarnpkg.com/@esbuild/android-x64/-/android-x64-0.27.2.tgz#a7ce9d0721825fc578f9292a76d9e53334480ba2"
+  resolved "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.27.2.tgz"
   integrity sha512-z8Ank4Byh4TJJOh4wpz8g2vDy75zFL0TlZlkUkEwYXuPSgX8yzep596n6mT7905kA9uHZsf/o2OJZubl2l3M7A==
 
 "@esbuild/darwin-arm64@0.27.2":
@@ -197,107 +202,107 @@
 
 "@esbuild/darwin-x64@0.27.2":
   version "0.27.2"
-  resolved "https://registry.yarnpkg.com/@esbuild/darwin-x64/-/darwin-x64-0.27.2.tgz#e741fa6b1abb0cd0364126ba34ca17fd5e7bf509"
+  resolved "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.27.2.tgz"
   integrity sha512-ZxtijOmlQCBWGwbVmwOF/UCzuGIbUkqB1faQRf5akQmxRJ1ujusWsb3CVfk/9iZKr2L5SMU5wPBi1UWbvL+VQA==
 
 "@esbuild/freebsd-arm64@0.27.2":
   version "0.27.2"
-  resolved "https://registry.yarnpkg.com/@esbuild/freebsd-arm64/-/freebsd-arm64-0.27.2.tgz#2b64e7116865ca172d4ce034114c21f3c93e397c"
+  resolved "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.27.2.tgz"
   integrity sha512-lS/9CN+rgqQ9czogxlMcBMGd+l8Q3Nj1MFQwBZJyoEKI50XGxwuzznYdwcav6lpOGv5BqaZXqvBSiB/kJ5op+g==
 
 "@esbuild/freebsd-x64@0.27.2":
   version "0.27.2"
-  resolved "https://registry.yarnpkg.com/@esbuild/freebsd-x64/-/freebsd-x64-0.27.2.tgz#e5252551e66f499e4934efb611812f3820e990bb"
+  resolved "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.27.2.tgz"
   integrity sha512-tAfqtNYb4YgPnJlEFu4c212HYjQWSO/w/h/lQaBK7RbwGIkBOuNKQI9tqWzx7Wtp7bTPaGC6MJvWI608P3wXYA==
 
-"@esbuild/linux-arm64@0.27.2":
-  version "0.27.2"
-  resolved "https://registry.yarnpkg.com/@esbuild/linux-arm64/-/linux-arm64-0.27.2.tgz#dc4acf235531cd6984f5d6c3b13dbfb7ddb303cb"
-  integrity sha512-hYxN8pr66NsCCiRFkHUAsxylNOcAQaxSSkHMMjcpx0si13t1LHFphxJZUiGwojB1a/Hd5OiPIqDdXONia6bhTw==
-
 "@esbuild/linux-arm@0.27.2":
   version "0.27.2"
-  resolved "https://registry.yarnpkg.com/@esbuild/linux-arm/-/linux-arm-0.27.2.tgz#56a900e39240d7d5d1d273bc053daa295c92e322"
+  resolved "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.27.2.tgz"
   integrity sha512-vWfq4GaIMP9AIe4yj1ZUW18RDhx6EPQKjwe7n8BbIecFtCQG4CfHGaHuh7fdfq+y3LIA2vGS/o9ZBGVxIDi9hw==
 
+"@esbuild/linux-arm64@0.27.2":
+  version "0.27.2"
+  resolved "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.27.2.tgz"
+  integrity sha512-hYxN8pr66NsCCiRFkHUAsxylNOcAQaxSSkHMMjcpx0si13t1LHFphxJZUiGwojB1a/Hd5OiPIqDdXONia6bhTw==
+
 "@esbuild/linux-ia32@0.27.2":
   version "0.27.2"
-  resolved "https://registry.yarnpkg.com/@esbuild/linux-ia32/-/linux-ia32-0.27.2.tgz#d4a36d473360f6870efcd19d52bbfff59a2ed1cc"
+  resolved "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.27.2.tgz"
   integrity sha512-MJt5BRRSScPDwG2hLelYhAAKh9imjHK5+NE/tvnRLbIqUWa+0E9N4WNMjmp/kXXPHZGqPLxggwVhz7QP8CTR8w==
 
 "@esbuild/linux-loong64@0.27.2":
   version "0.27.2"
-  resolved "https://registry.yarnpkg.com/@esbuild/linux-loong64/-/linux-loong64-0.27.2.tgz#fcf0ab8c3eaaf45891d0195d4961cb18b579716a"
+  resolved "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.27.2.tgz"
   integrity sha512-lugyF1atnAT463aO6KPshVCJK5NgRnU4yb3FUumyVz+cGvZbontBgzeGFO1nF+dPueHD367a2ZXe1NtUkAjOtg==
 
 "@esbuild/linux-mips64el@0.27.2":
   version "0.27.2"
-  resolved "https://registry.yarnpkg.com/@esbuild/linux-mips64el/-/linux-mips64el-0.27.2.tgz#598b67d34048bb7ee1901cb12e2a0a434c381c10"
+  resolved "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.27.2.tgz"
   integrity sha512-nlP2I6ArEBewvJ2gjrrkESEZkB5mIoaTswuqNFRv/WYd+ATtUpe9Y09RnJvgvdag7he0OWgEZWhviS1OTOKixw==
 
 "@esbuild/linux-ppc64@0.27.2":
   version "0.27.2"
-  resolved "https://registry.yarnpkg.com/@esbuild/linux-ppc64/-/linux-ppc64-0.27.2.tgz#3846c5df6b2016dab9bc95dde26c40f11e43b4c0"
+  resolved "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.27.2.tgz"
   integrity sha512-C92gnpey7tUQONqg1n6dKVbx3vphKtTHJaNG2Ok9lGwbZil6DrfyecMsp9CrmXGQJmZ7iiVXvvZH6Ml5hL6XdQ==
 
 "@esbuild/linux-riscv64@0.27.2":
   version "0.27.2"
-  resolved "https://registry.yarnpkg.com/@esbuild/linux-riscv64/-/linux-riscv64-0.27.2.tgz#173d4475b37c8d2c3e1707e068c174bb3f53d07d"
+  resolved "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.27.2.tgz"
   integrity sha512-B5BOmojNtUyN8AXlK0QJyvjEZkWwy/FKvakkTDCziX95AowLZKR6aCDhG7LeF7uMCXEJqwa8Bejz5LTPYm8AvA==
 
 "@esbuild/linux-s390x@0.27.2":
   version "0.27.2"
-  resolved "https://registry.yarnpkg.com/@esbuild/linux-s390x/-/linux-s390x-0.27.2.tgz#f7a4790105edcab8a5a31df26fbfac1aa3dacfab"
+  resolved "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.27.2.tgz"
   integrity sha512-p4bm9+wsPwup5Z8f4EpfN63qNagQ47Ua2znaqGH6bqLlmJ4bx97Y9JdqxgGZ6Y8xVTixUnEkoKSHcpRlDnNr5w==
 
 "@esbuild/linux-x64@0.27.2":
   version "0.27.2"
-  resolved "https://registry.yarnpkg.com/@esbuild/linux-x64/-/linux-x64-0.27.2.tgz#2ecc1284b1904aeb41e54c9ddc7fcd349b18f650"
+  resolved "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.27.2.tgz"
   integrity sha512-uwp2Tip5aPmH+NRUwTcfLb+W32WXjpFejTIOWZFw/v7/KnpCDKG66u4DLcurQpiYTiYwQ9B7KOeMJvLCu/OvbA==
 
 "@esbuild/netbsd-arm64@0.27.2":
   version "0.27.2"
-  resolved "https://registry.yarnpkg.com/@esbuild/netbsd-arm64/-/netbsd-arm64-0.27.2.tgz#e2863c2cd1501845995cb11adf26f7fe4be527b0"
+  resolved "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.27.2.tgz"
   integrity sha512-Kj6DiBlwXrPsCRDeRvGAUb/LNrBASrfqAIok+xB0LxK8CHqxZ037viF13ugfsIpePH93mX7xfJp97cyDuTZ3cw==
 
 "@esbuild/netbsd-x64@0.27.2":
   version "0.27.2"
-  resolved "https://registry.yarnpkg.com/@esbuild/netbsd-x64/-/netbsd-x64-0.27.2.tgz#93f7609e2885d1c0b5a1417885fba8d1fcc41272"
+  resolved "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.27.2.tgz"
   integrity sha512-HwGDZ0VLVBY3Y+Nw0JexZy9o/nUAWq9MlV7cahpaXKW6TOzfVno3y3/M8Ga8u8Yr7GldLOov27xiCnqRZf0tCA==
 
 "@esbuild/openbsd-arm64@0.27.2":
   version "0.27.2"
-  resolved "https://registry.yarnpkg.com/@esbuild/openbsd-arm64/-/openbsd-arm64-0.27.2.tgz#a1985604a203cdc325fd47542e106fafd698f02e"
+  resolved "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.27.2.tgz"
   integrity sha512-DNIHH2BPQ5551A7oSHD0CKbwIA/Ox7+78/AWkbS5QoRzaqlev2uFayfSxq68EkonB+IKjiuxBFoV8ESJy8bOHA==
 
 "@esbuild/openbsd-x64@0.27.2":
   version "0.27.2"
-  resolved "https://registry.yarnpkg.com/@esbuild/openbsd-x64/-/openbsd-x64-0.27.2.tgz#8209e46c42f1ffbe6e4ef77a32e1f47d404ad42a"
+  resolved "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.27.2.tgz"
   integrity sha512-/it7w9Nb7+0KFIzjalNJVR5bOzA9Vay+yIPLVHfIQYG/j+j9VTH84aNB8ExGKPU4AzfaEvN9/V4HV+F+vo8OEg==
 
 "@esbuild/openharmony-arm64@0.27.2":
   version "0.27.2"
-  resolved "https://registry.yarnpkg.com/@esbuild/openharmony-arm64/-/openharmony-arm64-0.27.2.tgz#8fade4441893d9cc44cbd7dcf3776f508ab6fb2f"
+  resolved "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.27.2.tgz"
   integrity sha512-LRBbCmiU51IXfeXk59csuX/aSaToeG7w48nMwA6049Y4J4+VbWALAuXcs+qcD04rHDuSCSRKdmY63sruDS5qag==
 
 "@esbuild/sunos-x64@0.27.2":
   version "0.27.2"
-  resolved "https://registry.yarnpkg.com/@esbuild/sunos-x64/-/sunos-x64-0.27.2.tgz#980d4b9703a16f0f07016632424fc6d9a789dfc2"
+  resolved "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.27.2.tgz"
   integrity sha512-kMtx1yqJHTmqaqHPAzKCAkDaKsffmXkPHThSfRwZGyuqyIeBvf08KSsYXl+abf5HDAPMJIPnbBfXvP2ZC2TfHg==
 
 "@esbuild/win32-arm64@0.27.2":
   version "0.27.2"
-  resolved "https://registry.yarnpkg.com/@esbuild/win32-arm64/-/win32-arm64-0.27.2.tgz#1c09a3633c949ead3d808ba37276883e71f6111a"
+  resolved "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.27.2.tgz"
   integrity sha512-Yaf78O/B3Kkh+nKABUF++bvJv5Ijoy9AN1ww904rOXZFLWVc5OLOfL56W+C8F9xn5JQZa3UX6m+IktJnIb1Jjg==
 
 "@esbuild/win32-ia32@0.27.2":
   version "0.27.2"
-  resolved "https://registry.yarnpkg.com/@esbuild/win32-ia32/-/win32-ia32-0.27.2.tgz#1b1e3a63ad4bef82200fef4e369e0fff7009eee5"
+  resolved "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.27.2.tgz"
   integrity sha512-Iuws0kxo4yusk7sw70Xa2E2imZU5HoixzxfGCdxwBdhiDgt9vX9VUCBhqcwY7/uh//78A1hMkkROMJq9l27oLQ==
 
 "@esbuild/win32-x64@0.27.2":
   version "0.27.2"
-  resolved "https://registry.yarnpkg.com/@esbuild/win32-x64/-/win32-x64-0.27.2.tgz#9e585ab6086bef994c6e8a5b3a0481219ada862b"
+  resolved "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.27.2.tgz"
   integrity sha512-sRdU18mcKf7F+YgheI/zGf5alZatMUTKj/jNS6l744f9u3WFu4v7twcUI9vu4mknF4Y9aDlblIie0IM+5xxaqQ==
 
 "@jridgewell/gen-mapping@^0.3.12", "@jridgewell/gen-mapping@^0.3.2", "@jridgewell/gen-mapping@^0.3.5":
@@ -326,7 +331,7 @@
   resolved "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz"
   integrity sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==
 
-"@jridgewell/trace-mapping@^0.3.24", "@jridgewell/trace-mapping@^0.3.28":
+"@jridgewell/trace-mapping@^0.3.24", "@jridgewell/trace-mapping@^0.3.28", "@jridgewell/trace-mapping@^0.3.31":
   version "0.3.31"
   resolved "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.31.tgz"
   integrity sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==
@@ -342,7 +347,7 @@
     "@nodelib/fs.stat" "2.0.5"
     run-parallel "^1.1.9"
 
-"@nodelib/fs.stat@2.0.5", "@nodelib/fs.stat@^2.0.2":
+"@nodelib/fs.stat@^2.0.2", "@nodelib/fs.stat@2.0.5":
   version "2.0.5"
   resolved "https://registry.npmjs.org/@nodelib/fs.stat/-/fs.stat-2.0.5.tgz"
   integrity sha512-RkhPPp2zrqDAQA/2jNhnztcPAlv64XdhIp7a7454A5ovI7Bukxgt7MX7udwAu3zg1DcpPU0rz3VV1SeaqvY4+A==
@@ -392,12 +397,12 @@
 
 "@rollup/rollup-android-arm-eabi@4.56.0":
   version "4.56.0"
-  resolved "https://registry.yarnpkg.com/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.56.0.tgz#067cfcd81f1c1bfd92aefe3ad5ef1523549d5052"
+  resolved "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.56.0.tgz"
   integrity sha512-LNKIPA5k8PF1+jAFomGe3qN3bbIgJe/IlpDBwuVjrDKrJhVWywgnJvflMt/zkbVNLFtF1+94SljYQS6e99klnw==
 
 "@rollup/rollup-android-arm64@4.56.0":
   version "4.56.0"
-  resolved "https://registry.yarnpkg.com/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.56.0.tgz#85e39a44034d7d4e4fee2a1616f0bddb85a80517"
+  resolved "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.56.0.tgz"
   integrity sha512-lfbVUbelYqXlYiU/HApNMJzT1E87UPGvzveGg2h0ktUNlOCxKlWuJ9jtfvs1sKHdwU4fzY7Pl8sAl49/XaEk6Q==
 
 "@rollup/rollup-darwin-arm64@4.56.0":
@@ -407,112 +412,112 @@
 
 "@rollup/rollup-darwin-x64@4.56.0":
   version "4.56.0"
-  resolved "https://registry.yarnpkg.com/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.56.0.tgz#89ae6c66b1451609bd1f297da9384463f628437d"
+  resolved "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.56.0.tgz"
   integrity sha512-1vXe1vcMOssb/hOF8iv52A7feWW2xnu+c8BV4t1F//m9QVLTfNVpEdja5ia762j/UEJe2Z1jAmEqZAK42tVW3g==
 
 "@rollup/rollup-freebsd-arm64@4.56.0":
   version "4.56.0"
-  resolved "https://registry.yarnpkg.com/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.56.0.tgz#cdbdb9947b26e76c188a31238c10639347413628"
+  resolved "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.56.0.tgz"
   integrity sha512-bof7fbIlvqsyv/DtaXSck4VYQ9lPtoWNFCB/JY4snlFuJREXfZnm+Ej6yaCHfQvofJDXLDMTVxWscVSuQvVWUQ==
 
 "@rollup/rollup-freebsd-x64@4.56.0":
   version "4.56.0"
-  resolved "https://registry.yarnpkg.com/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.56.0.tgz#9b1458d07b6e040be16ee36d308a2c9520f7f7cc"
+  resolved "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.56.0.tgz"
   integrity sha512-KNa6lYHloW+7lTEkYGa37fpvPq+NKG/EHKM8+G/g9WDU7ls4sMqbVRV78J6LdNuVaeeK5WB9/9VAFbKxcbXKYg==
 
 "@rollup/rollup-linux-arm-gnueabihf@4.56.0":
   version "4.56.0"
-  resolved "https://registry.yarnpkg.com/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.56.0.tgz#1d50ded7c965d5f125f5832c971ad5b287befef7"
+  resolved "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.56.0.tgz"
   integrity sha512-E8jKK87uOvLrrLN28jnAAAChNq5LeCd2mGgZF+fGF5D507WlG/Noct3lP/QzQ6MrqJ5BCKNwI9ipADB6jyiq2A==
 
 "@rollup/rollup-linux-arm-musleabihf@4.56.0":
   version "4.56.0"
-  resolved "https://registry.yarnpkg.com/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.56.0.tgz#53597e319b7e65990d3bc2a5048097384814c179"
+  resolved "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.56.0.tgz"
   integrity sha512-jQosa5FMYF5Z6prEpTCCmzCXz6eKr/tCBssSmQGEeozA9tkRUty/5Vx06ibaOP9RCrW1Pvb8yp3gvZhHwTDsJw==
 
 "@rollup/rollup-linux-arm64-gnu@4.56.0":
   version "4.56.0"
-  resolved "https://registry.yarnpkg.com/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.56.0.tgz#597002909dec198ca4bdccb25f043d32db3d6283"
+  resolved "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.56.0.tgz"
   integrity sha512-uQVoKkrC1KGEV6udrdVahASIsaF8h7iLG0U0W+Xn14ucFwi6uS539PsAr24IEF9/FoDtzMeeJXJIBo5RkbNWvQ==
 
 "@rollup/rollup-linux-arm64-musl@4.56.0":
   version "4.56.0"
-  resolved "https://registry.yarnpkg.com/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.56.0.tgz#286f0e0f799545ce288bdc5a7c777261fcba3d54"
+  resolved "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.56.0.tgz"
   integrity sha512-vLZ1yJKLxhQLFKTs42RwTwa6zkGln+bnXc8ueFGMYmBTLfNu58sl5/eXyxRa2RarTkJbXl8TKPgfS6V5ijNqEA==
 
 "@rollup/rollup-linux-loong64-gnu@4.56.0":
   version "4.56.0"
-  resolved "https://registry.yarnpkg.com/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.56.0.tgz#1fab07fa1a4f8d3697735b996517f1bae0ba101b"
+  resolved "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.56.0.tgz"
   integrity sha512-FWfHOCub564kSE3xJQLLIC/hbKqHSVxy8vY75/YHHzWvbJL7aYJkdgwD/xGfUlL5UV2SB7otapLrcCj2xnF1dg==
 
 "@rollup/rollup-linux-loong64-musl@4.56.0":
   version "4.56.0"
-  resolved "https://registry.yarnpkg.com/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.56.0.tgz#efc2cb143d6c067f95205482afb177f78ed9ea3d"
+  resolved "https://registry.npmjs.org/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.56.0.tgz"
   integrity sha512-z1EkujxIh7nbrKL1lmIpqFTc/sr0u8Uk0zK/qIEFldbt6EDKWFk/pxFq3gYj4Bjn3aa9eEhYRlL3H8ZbPT1xvA==
 
 "@rollup/rollup-linux-ppc64-gnu@4.56.0":
   version "4.56.0"
-  resolved "https://registry.yarnpkg.com/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.56.0.tgz#e8de8bd3463f96b92b7dfb7f151fd80ffe8a937c"
+  resolved "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.56.0.tgz"
   integrity sha512-iNFTluqgdoQC7AIE8Q34R3AuPrJGJirj5wMUErxj22deOcY7XwZRaqYmB6ZKFHoVGqRcRd0mqO+845jAibKCkw==
 
 "@rollup/rollup-linux-ppc64-musl@4.56.0":
   version "4.56.0"
-  resolved "https://registry.yarnpkg.com/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.56.0.tgz#8c508fe28a239da83b3a9da75bcf093186e064b4"
+  resolved "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.56.0.tgz"
   integrity sha512-MtMeFVlD2LIKjp2sE2xM2slq3Zxf9zwVuw0jemsxvh1QOpHSsSzfNOTH9uYW9i1MXFxUSMmLpeVeUzoNOKBaWg==
 
 "@rollup/rollup-linux-riscv64-gnu@4.56.0":
   version "4.56.0"
-  resolved "https://registry.yarnpkg.com/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.56.0.tgz#ff6d51976e0830732880770a9e18553136b8d92b"
+  resolved "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.56.0.tgz"
   integrity sha512-in+v6wiHdzzVhYKXIk5U74dEZHdKN9KH0Q4ANHOTvyXPG41bajYRsy7a8TPKbYPl34hU7PP7hMVHRvv/5aCSew==
 
 "@rollup/rollup-linux-riscv64-musl@4.56.0":
   version "4.56.0"
-  resolved "https://registry.yarnpkg.com/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.56.0.tgz#325fb35eefc7e81d75478318f0deee1e4a111493"
+  resolved "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.56.0.tgz"
   integrity sha512-yni2raKHB8m9NQpI9fPVwN754mn6dHQSbDTwxdr9SE0ks38DTjLMMBjrwvB5+mXrX+C0npX0CVeCUcvvvD8CNQ==
 
 "@rollup/rollup-linux-s390x-gnu@4.56.0":
   version "4.56.0"
-  resolved "https://registry.yarnpkg.com/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.56.0.tgz#37410fabb5d3ba4ad34abcfbe9ba9b6288413f30"
+  resolved "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.56.0.tgz"
   integrity sha512-zhLLJx9nQPu7wezbxt2ut+CI4YlXi68ndEve16tPc/iwoylWS9B3FxpLS2PkmfYgDQtosah07Mj9E0khc3Y+vQ==
 
 "@rollup/rollup-linux-x64-gnu@4.56.0":
   version "4.56.0"
-  resolved "https://registry.yarnpkg.com/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.56.0.tgz#8ef907a53b2042068fc03fcc6a641e2b02276eca"
+  resolved "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.56.0.tgz"
   integrity sha512-MVC6UDp16ZSH7x4rtuJPAEoE1RwS8N4oK9DLHy3FTEdFoUTCFVzMfJl/BVJ330C+hx8FfprA5Wqx4FhZXkj2Kw==
 
 "@rollup/rollup-linux-x64-musl@4.56.0":
   version "4.56.0"
-  resolved "https://registry.yarnpkg.com/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.56.0.tgz#61b9ba09ea219e0174b3f35a6ad2afc94bdd5662"
+  resolved "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.56.0.tgz"
   integrity sha512-ZhGH1eA4Qv0lxaV00azCIS1ChedK0V32952Md3FtnxSqZTBTd6tgil4nZT5cU8B+SIw3PFYkvyR4FKo2oyZIHA==
 
 "@rollup/rollup-openbsd-x64@4.56.0":
   version "4.56.0"
-  resolved "https://registry.yarnpkg.com/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.56.0.tgz#fc4e54133134c1787d0b016ffdd5aeb22a5effd3"
+  resolved "https://registry.npmjs.org/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.56.0.tgz"
   integrity sha512-O16XcmyDeFI9879pEcmtWvD/2nyxR9mF7Gs44lf1vGGx8Vg2DRNx11aVXBEqOQhWb92WN4z7fW/q4+2NYzCbBA==
 
 "@rollup/rollup-openharmony-arm64@4.56.0":
   version "4.56.0"
-  resolved "https://registry.yarnpkg.com/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.56.0.tgz#959ae225b1eeea0cc5b7c9f88e4834330fb6cd09"
+  resolved "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.56.0.tgz"
   integrity sha512-LhN/Reh+7F3RCgQIRbgw8ZMwUwyqJM+8pXNT6IIJAqm2IdKkzpCh/V9EdgOMBKuebIrzswqy4ATlrDgiOwbRcQ==
 
 "@rollup/rollup-win32-arm64-msvc@4.56.0":
   version "4.56.0"
-  resolved "https://registry.yarnpkg.com/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.56.0.tgz#842acd38869fa1cbdbc240c76c67a86f93444c27"
+  resolved "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.56.0.tgz"
   integrity sha512-kbFsOObXp3LBULg1d3JIUQMa9Kv4UitDmpS+k0tinPBz3watcUiV2/LUDMMucA6pZO3WGE27P7DsfaN54l9ing==
 
 "@rollup/rollup-win32-ia32-msvc@4.56.0":
   version "4.56.0"
-  resolved "https://registry.yarnpkg.com/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.56.0.tgz#7ab654def4042df44cb29f8ed9d5044e850c66d5"
+  resolved "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.56.0.tgz"
   integrity sha512-vSSgny54D6P4vf2izbtFm/TcWYedw7f8eBrOiGGecyHyQB9q4Kqentjaj8hToe+995nob/Wv48pDqL5a62EWtg==
 
 "@rollup/rollup-win32-x64-gnu@4.56.0":
   version "4.56.0"
-  resolved "https://registry.yarnpkg.com/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.56.0.tgz#7426cdec1b01d2382ffd5cda83cbdd1c8efb3ca6"
+  resolved "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.56.0.tgz"
   integrity sha512-FeCnkPCTHQJFbiGG49KjV5YGW/8b9rrXAM2Mz2kiIoktq2qsJxRD5giEMEOD2lPdgs72upzefaUvS+nc8E3UzQ==
 
 "@rollup/rollup-win32-x64-msvc@4.56.0":
   version "4.56.0"
-  resolved "https://registry.yarnpkg.com/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.56.0.tgz#9eec0212732a432c71bde0350bc40b673d15b2db"
+  resolved "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.56.0.tgz"
   integrity sha512-H8AE9Ur/t0+1VXujj90w0HrSOuv0Nq9r1vSZF2t5km20NTfosQsGGUXDaKdQZzwuLts7IyL1fYT4hM95TI9c4g==
 
 "@socket.io/component-emitter@~3.1.0":
@@ -556,52 +561,52 @@
 
 "@tauri-apps/cli-darwin-x64@2.9.6":
   version "2.9.6"
-  resolved "https://registry.yarnpkg.com/@tauri-apps/cli-darwin-x64/-/cli-darwin-x64-2.9.6.tgz#7beb6ba8218002d7e160764326ce03407e76305d"
+  resolved "https://registry.npmjs.org/@tauri-apps/cli-darwin-x64/-/cli-darwin-x64-2.9.6.tgz"
   integrity sha512-oWh74WmqbERwwrwcueJyY6HYhgCksUc6NT7WKeXyrlY/FPmNgdyQAgcLuTSkhRFuQ6zh4Np1HZpOqCTpeZBDcw==
 
 "@tauri-apps/cli-linux-arm-gnueabihf@2.9.6":
   version "2.9.6"
-  resolved "https://registry.yarnpkg.com/@tauri-apps/cli-linux-arm-gnueabihf/-/cli-linux-arm-gnueabihf-2.9.6.tgz#523ddcd86a99bdda5156bd9de96dfd3e4fa75b7f"
+  resolved "https://registry.npmjs.org/@tauri-apps/cli-linux-arm-gnueabihf/-/cli-linux-arm-gnueabihf-2.9.6.tgz"
   integrity sha512-/zde3bFroFsNXOHN204DC2qUxAcAanUjVXXSdEGmhwMUZeAQalNj5cz2Qli2elsRjKN/hVbZOJj0gQ5zaYUjSg==
 
 "@tauri-apps/cli-linux-arm64-gnu@2.9.6":
   version "2.9.6"
-  resolved "https://registry.yarnpkg.com/@tauri-apps/cli-linux-arm64-gnu/-/cli-linux-arm64-gnu-2.9.6.tgz#60b4cbd4b8b97c5f5be6cc70fa75455b5a6d6292"
+  resolved "https://registry.npmjs.org/@tauri-apps/cli-linux-arm64-gnu/-/cli-linux-arm64-gnu-2.9.6.tgz"
   integrity sha512-pvbljdhp9VOo4RnID5ywSxgBs7qiylTPlK56cTk7InR3kYSTJKYMqv/4Q/4rGo/mG8cVppesKIeBMH42fw6wjg==
 
 "@tauri-apps/cli-linux-arm64-musl@2.9.6":
   version "2.9.6"
-  resolved "https://registry.yarnpkg.com/@tauri-apps/cli-linux-arm64-musl/-/cli-linux-arm64-musl-2.9.6.tgz#ce5e5396db6c7f22b80154757479b1486163364a"
+  resolved "https://registry.npmjs.org/@tauri-apps/cli-linux-arm64-musl/-/cli-linux-arm64-musl-2.9.6.tgz"
   integrity sha512-02TKUndpodXBCR0oP//6dZWGYcc22Upf2eP27NvC6z0DIqvkBBFziQUcvi2n6SrwTRL0yGgQjkm9K5NIn8s6jw==
 
 "@tauri-apps/cli-linux-riscv64-gnu@2.9.6":
   version "2.9.6"
-  resolved "https://registry.yarnpkg.com/@tauri-apps/cli-linux-riscv64-gnu/-/cli-linux-riscv64-gnu-2.9.6.tgz#aa8ec23d62cbb85a75c3e172637e78f485dbfcf8"
+  resolved "https://registry.npmjs.org/@tauri-apps/cli-linux-riscv64-gnu/-/cli-linux-riscv64-gnu-2.9.6.tgz"
   integrity sha512-fmp1hnulbqzl1GkXl4aTX9fV+ubHw2LqlLH1PE3BxZ11EQk+l/TmiEongjnxF0ie4kV8DQfDNJ1KGiIdWe1GvQ==
 
 "@tauri-apps/cli-linux-x64-gnu@2.9.6":
   version "2.9.6"
-  resolved "https://registry.yarnpkg.com/@tauri-apps/cli-linux-x64-gnu/-/cli-linux-x64-gnu-2.9.6.tgz#036c0463c5eee2298ed6ca8cb2838738816c7290"
+  resolved "https://registry.npmjs.org/@tauri-apps/cli-linux-x64-gnu/-/cli-linux-x64-gnu-2.9.6.tgz"
   integrity sha512-vY0le8ad2KaV1PJr+jCd8fUF9VOjwwQP/uBuTJvhvKTloEwxYA/kAjKK9OpIslGA9m/zcnSo74czI6bBrm2sYA==
 
 "@tauri-apps/cli-linux-x64-musl@2.9.6":
   version "2.9.6"
-  resolved "https://registry.yarnpkg.com/@tauri-apps/cli-linux-x64-musl/-/cli-linux-x64-musl-2.9.6.tgz#62b05db3d28b0f12c150836a387bd572de44f5be"
+  resolved "https://registry.npmjs.org/@tauri-apps/cli-linux-x64-musl/-/cli-linux-x64-musl-2.9.6.tgz"
   integrity sha512-TOEuB8YCFZTWVDzsO2yW0+zGcoMiPPwcUgdnW1ODnmgfwccpnihDRoks+ABT1e3fHb1ol8QQWsHSCovb3o2ENQ==
 
 "@tauri-apps/cli-win32-arm64-msvc@2.9.6":
   version "2.9.6"
-  resolved "https://registry.yarnpkg.com/@tauri-apps/cli-win32-arm64-msvc/-/cli-win32-arm64-msvc-2.9.6.tgz#01f69ba09a6581e70bdfa206c5801b64b329d28d"
+  resolved "https://registry.npmjs.org/@tauri-apps/cli-win32-arm64-msvc/-/cli-win32-arm64-msvc-2.9.6.tgz"
   integrity sha512-ujmDGMRc4qRLAnj8nNG26Rlz9klJ0I0jmZs2BPpmNNf0gM/rcVHhqbEkAaHPTBVIrtUdf7bGvQAD2pyIiUrBHQ==
 
 "@tauri-apps/cli-win32-ia32-msvc@2.9.6":
   version "2.9.6"
-  resolved "https://registry.yarnpkg.com/@tauri-apps/cli-win32-ia32-msvc/-/cli-win32-ia32-msvc-2.9.6.tgz#b36c60db5119d74f126d4c4d8288d1c6ae4b45f0"
+  resolved "https://registry.npmjs.org/@tauri-apps/cli-win32-ia32-msvc/-/cli-win32-ia32-msvc-2.9.6.tgz"
   integrity sha512-S4pT0yAJgFX8QRCyKA1iKjZ9Q/oPjCZf66A/VlG5Yw54Nnr88J1uBpmenINbXxzyhduWrIXBaUbEY1K80ZbpMg==
 
 "@tauri-apps/cli-win32-x64-msvc@2.9.6":
   version "2.9.6"
-  resolved "https://registry.yarnpkg.com/@tauri-apps/cli-win32-x64-msvc/-/cli-win32-x64-msvc-2.9.6.tgz#d58c9f8af835b7e4fc30e201e979342c70bea426"
+  resolved "https://registry.npmjs.org/@tauri-apps/cli-win32-x64-msvc/-/cli-win32-x64-msvc-2.9.6.tgz"
   integrity sha512-ldWuWSSkWbKOPjQMJoYVj9wLHcOniv7diyI5UAJ4XsBdtaFB0pKHQsqw/ItUma0VXGC7vB4E9fZjivmxur60aw==
 
 "@tauri-apps/cli@^2":
@@ -668,7 +673,20 @@
   dependencies:
     "@babel/types" "^7.28.2"
 
-"@types/estree@1.0.8", "@types/estree@^1.0.0":
+"@types/chai@^5.2.2":
+  version "5.2.3"
+  resolved "https://registry.npmjs.org/@types/chai/-/chai-5.2.3.tgz"
+  integrity sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==
+  dependencies:
+    "@types/deep-eql" "*"
+    assertion-error "^2.0.1"
+
+"@types/deep-eql@*":
+  version "4.0.2"
+  resolved "https://registry.npmjs.org/@types/deep-eql/-/deep-eql-4.0.2.tgz"
+  integrity sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==
+
+"@types/estree@^1.0.0", "@types/estree@1.0.8":
   version "1.0.8"
   resolved "https://registry.npmjs.org/@types/estree/-/estree-1.0.8.tgz"
   integrity sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==
@@ -678,7 +696,7 @@
   resolved "https://registry.npmjs.org/@types/history/-/history-4.7.11.tgz"
   integrity sha512-qjDJRrmvBMiTx+jyLxvLfJU7UznFuokDv4f3WRuriHKERccVpFU+8XMQUAbDzoiJCsmexxRExQeMwwCdamSKDA==
 
-"@types/node@^25.0.10":
+"@types/node@^20.0.0 || ^22.0.0 || >=24.0.0", "@types/node@^20.19.0 || >=22.12.0", "@types/node@^25.0.10":
   version "25.0.10"
   resolved "https://registry.npmjs.org/@types/node/-/node-25.0.10.tgz"
   integrity sha512-zWW5KPngR/yvakJgGOmZ5vTBemDoSqF3AcV/LrO5u5wTWyEAVVh+IT39G4gtyAkh3CtTZs8aX/yRM82OfzHJRg==
@@ -707,7 +725,7 @@
     "@types/history" "^4.7.11"
     "@types/react" "*"
 
-"@types/react@*", "@types/react@^19.1.8":
+"@types/react@*", "@types/react@^18.2.25 || ^19", "@types/react@^19.1.8", "@types/react@^19.2.0", "@types/react@>=18.0.0":
   version "19.2.9"
   resolved "https://registry.npmjs.org/@types/react/-/react-19.2.9.tgz"
   integrity sha512-Lpo8kgb/igvMIPeNV2rsYKTgaORYdO1XGVZ4Qz3akwOj0ySGYMPlQWa8BaLn0G63D1aSaAQ5ldR06wCpChQCjA==
@@ -738,6 +756,80 @@
     "@types/babel__core" "^7.20.5"
     react-refresh "^0.17.0"
 
+"@vitest/coverage-v8@^4.0.18":
+  version "4.0.18"
+  resolved "https://registry.npmjs.org/@vitest/coverage-v8/-/coverage-v8-4.0.18.tgz"
+  integrity sha512-7i+N2i0+ME+2JFZhfuz7Tg/FqKtilHjGyGvoHYQ6iLV0zahbsJ9sljC9OcFcPDbhYKCet+sG8SsVqlyGvPflZg==
+  dependencies:
+    "@bcoe/v8-coverage" "^1.0.2"
+    "@vitest/utils" "4.0.18"
+    ast-v8-to-istanbul "^0.3.10"
+    istanbul-lib-coverage "^3.2.2"
+    istanbul-lib-report "^3.0.1"
+    istanbul-reports "^3.2.0"
+    magicast "^0.5.1"
+    obug "^2.1.1"
+    std-env "^3.10.0"
+    tinyrainbow "^3.0.3"
+
+"@vitest/expect@4.0.18":
+  version "4.0.18"
+  resolved "https://registry.npmjs.org/@vitest/expect/-/expect-4.0.18.tgz"
+  integrity sha512-8sCWUyckXXYvx4opfzVY03EOiYVxyNrHS5QxX3DAIi5dpJAAkyJezHCP77VMX4HKA2LDT/Jpfo8i2r5BE3GnQQ==
+  dependencies:
+    "@standard-schema/spec" "^1.0.0"
+    "@types/chai" "^5.2.2"
+    "@vitest/spy" "4.0.18"
+    "@vitest/utils" "4.0.18"
+    chai "^6.2.1"
+    tinyrainbow "^3.0.3"
+
+"@vitest/mocker@4.0.18":
+  version "4.0.18"
+  resolved "https://registry.npmjs.org/@vitest/mocker/-/mocker-4.0.18.tgz"
+  integrity sha512-HhVd0MDnzzsgevnOWCBj5Otnzobjy5wLBe4EdeeFGv8luMsGcYqDuFRMcttKWZA5vVO8RFjexVovXvAM4JoJDQ==
+  dependencies:
+    "@vitest/spy" "4.0.18"
+    estree-walker "^3.0.3"
+    magic-string "^0.30.21"
+
+"@vitest/pretty-format@4.0.18":
+  version "4.0.18"
+  resolved "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-4.0.18.tgz"
+  integrity sha512-P24GK3GulZWC5tz87ux0m8OADrQIUVDPIjjj65vBXYG17ZeU3qD7r+MNZ1RNv4l8CGU2vtTRqixrOi9fYk/yKw==
+  dependencies:
+    tinyrainbow "^3.0.3"
+
+"@vitest/runner@4.0.18":
+  version "4.0.18"
+  resolved "https://registry.npmjs.org/@vitest/runner/-/runner-4.0.18.tgz"
+  integrity sha512-rpk9y12PGa22Jg6g5M3UVVnTS7+zycIGk9ZNGN+m6tZHKQb7jrP7/77WfZy13Y/EUDd52NDsLRQhYKtv7XfPQw==
+  dependencies:
+    "@vitest/utils" "4.0.18"
+    pathe "^2.0.3"
+
+"@vitest/snapshot@4.0.18":
+  version "4.0.18"
+  resolved "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-4.0.18.tgz"
+  integrity sha512-PCiV0rcl7jKQjbgYqjtakly6T1uwv/5BQ9SwBLekVg/EaYeQFPiXcgrC2Y7vDMA8dM1SUEAEV82kgSQIlXNMvA==
+  dependencies:
+    "@vitest/pretty-format" "4.0.18"
+    magic-string "^0.30.21"
+    pathe "^2.0.3"
+
+"@vitest/spy@4.0.18":
+  version "4.0.18"
+  resolved "https://registry.npmjs.org/@vitest/spy/-/spy-4.0.18.tgz"
+  integrity sha512-cbQt3PTSD7P2OARdVW3qWER5EGq7PHlvE+QfzSC0lbwO+xnt7+XH06ZzFjFRgzUX//JmpxrCu92VdwvEPlWSNw==
+
+"@vitest/utils@4.0.18":
+  version "4.0.18"
+  resolved "https://registry.npmjs.org/@vitest/utils/-/utils-4.0.18.tgz"
+  integrity sha512-msMRKLMVLWygpK3u2Hybgi4MNjcYJvwTb0Ru09+fOyCXIgT5raYP041DRRdiJiI3k/2U6SEbAETB3YtBrUkCFA==
+  dependencies:
+    "@vitest/pretty-format" "4.0.18"
+    tinyrainbow "^3.0.3"
+
 any-promise@^1.0.0:
   version "1.3.0"
   resolved "https://registry.npmjs.org/any-promise/-/any-promise-1.3.0.tgz"
@@ -776,6 +868,20 @@ assert@^2.0.0:
     object.assign "^4.1.4"
     util "^0.12.5"
 
+assertion-error@^2.0.1:
+  version "2.0.1"
+  resolved "https://registry.npmjs.org/assertion-error/-/assertion-error-2.0.1.tgz"
+  integrity sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==
+
+ast-v8-to-istanbul@^0.3.10:
+  version "0.3.10"
+  resolved "https://registry.npmjs.org/ast-v8-to-istanbul/-/ast-v8-to-istanbul-0.3.10.tgz"
+  integrity sha512-p4K7vMz2ZSk3wN8l5o3y2bJAoZXT3VuJI5OLTATY/01CYWumWvwkUw0SqDBnNq6IiTO3qDa1eSQDibAV8g7XOQ==
+  dependencies:
+    "@jridgewell/trace-mapping" "^0.3.31"
+    estree-walker "^3.0.3"
+    js-tokens "^9.0.1"
+
 async-mutex@^0.3.0:
   version "0.3.2"
   resolved "https://registry.npmjs.org/async-mutex/-/async-mutex-0.3.2.tgz"
@@ -821,7 +927,17 @@ binary-extensions@^2.0.0:
   resolved "https://registry.npmjs.org/binary-extensions/-/binary-extensions-2.3.0.tgz"
   integrity sha512-Ceh+7ox5qe7LJuLHoY0feh3pHuUDHAcRUeyL2VYghZwfpkNIy/+8Ocg0a3UuSoYzavmylwuLWQOf3hl0jjMMIw==
 
-bn.js@^4.0.0, bn.js@^4.1.0, bn.js@^4.11.9:
+bn.js@^4.0.0:
+  version "4.12.2"
+  resolved "https://registry.npmjs.org/bn.js/-/bn.js-4.12.2.tgz"
+  integrity sha512-n4DSx829VRTRByMRGdjQ9iqsN0Bh4OolPsFnaZBLcbi8iXcB+kJ9s7EnRt4wILZNV3kPLHkRVfOc/HvhC3ovDw==
+
+bn.js@^4.1.0:
+  version "4.12.2"
+  resolved "https://registry.npmjs.org/bn.js/-/bn.js-4.12.2.tgz"
+  integrity sha512-n4DSx829VRTRByMRGdjQ9iqsN0Bh4OolPsFnaZBLcbi8iXcB+kJ9s7EnRt4wILZNV3kPLHkRVfOc/HvhC3ovDw==
+
+bn.js@^4.11.9:
   version "4.12.2"
   resolved "https://registry.npmjs.org/bn.js/-/bn.js-4.12.2.tgz"
   integrity sha512-n4DSx829VRTRByMRGdjQ9iqsN0Bh4OolPsFnaZBLcbi8iXcB+kJ9s7EnRt4wILZNV3kPLHkRVfOc/HvhC3ovDw==
@@ -912,7 +1028,7 @@ browserify-zlib@^0.2.0:
   dependencies:
     pako "~1.0.5"
 
-browserslist@^4.24.0, browserslist@^4.28.1:
+browserslist@^4.24.0, browserslist@^4.28.1, "browserslist@>= 4.21.0":
   version "4.28.1"
   resolved "https://registry.npmjs.org/browserslist/-/browserslist-4.28.1.tgz"
   integrity sha512-ZC5Bd0LgJXgwGqUknZY/vkUQ04r8NXnJZ3yYi4vDmSiZmC/pdSN0NbNRPxZpbtO4uAfDUAFffO8IZoM3Gj8IkA==
@@ -992,6 +1108,11 @@ caniuse-lite@^1.0.30001759, caniuse-lite@^1.0.30001760:
   resolved "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001766.tgz"
   integrity sha512-4C0lfJ0/YPjJQHagaE9x2Elb69CIqEPZeG0anQt9SIvIoOH4a4uaRl73IavyO+0qZh6MDLH//DrXThEYKHkmYA==
 
+chai@^6.2.1:
+  version "6.2.2"
+  resolved "https://registry.npmjs.org/chai/-/chai-6.2.2.tgz"
+  integrity sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==
+
 chokidar@^3.6.0:
   version "3.6.0"
   resolved "https://registry.npmjs.org/chokidar/-/chokidar-3.6.0.tgz"
@@ -1110,7 +1231,7 @@ csstype@^3.2.2:
   resolved "https://registry.npmjs.org/csstype/-/csstype-3.2.3.tgz"
   integrity sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==
 
-d@1, d@^1.0.1, d@^1.0.2:
+d@^1.0.1, d@^1.0.2, d@1:
   version "1.0.2"
   resolved "https://registry.npmjs.org/d/-/d-1.0.2.tgz"
   integrity sha512-MOqHvMWF9/9MX6nza0KgvFH4HpMU0EF5uUDXqX/BtxtU8NfB0QzRtJ8Oe/6SuS4kbhyzVJwjd97EA4PKrzJ8bw==
@@ -1275,6 +1396,11 @@ es-errors@^1.3.0:
   resolved "https://registry.npmjs.org/es-errors/-/es-errors-1.3.0.tgz"
   integrity sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==
 
+es-module-lexer@^1.7.0:
+  version "1.7.0"
+  resolved "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-1.7.0.tgz"
+  integrity sha512-jEQoCwk8hyb2AZziIOLhDqpm5+2ww5uIE6lkO/6jcOCusfk6LhMHpXXfBLXTZ7Ydyt0j4VoUQv6uGNYbdW+kBA==
+
 es-object-atoms@^1.0.0, es-object-atoms@^1.1.1:
   version "1.1.1"
   resolved "https://registry.npmjs.org/es-object-atoms/-/es-object-atoms-1.1.1.tgz"
@@ -1361,6 +1487,13 @@ estree-walker@^2.0.2:
   resolved "https://registry.npmjs.org/estree-walker/-/estree-walker-2.0.2.tgz"
   integrity sha512-Rfkk/Mp/DL7JVje3u18FxFujQlTNR2q6QfMSMB7AvCBx91NGj/ba3kCfza0f6dVDbw7YlRf/nDrn7pQrCCyQ/w==
 
+estree-walker@^3.0.3:
+  version "3.0.3"
+  resolved "https://registry.npmjs.org/estree-walker/-/estree-walker-3.0.3.tgz"
+  integrity sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==
+  dependencies:
+    "@types/estree" "^1.0.0"
+
 event-emitter@^0.3.5:
   version "0.3.5"
   resolved "https://registry.npmjs.org/event-emitter/-/event-emitter-0.3.5.tgz"
@@ -1382,6 +1515,11 @@ evp_bytestokey@^1.0.0, evp_bytestokey@^1.0.3:
     md5.js "^1.3.4"
     safe-buffer "^5.1.1"
 
+expect-type@^1.2.2:
+  version "1.3.0"
+  resolved "https://registry.npmjs.org/expect-type/-/expect-type-1.3.0.tgz"
+  integrity sha512-knvyeauYhqjOYvQ66MznSMs83wmHrCycNEN6Ao+2AeYEfxUIkuiVxdEa1qlGEPK+We3n0THiDciYSsCcgW/DoA==
+
 ext@^1.7.0:
   version "1.7.0"
   resolved "https://registry.npmjs.org/ext/-/ext-1.7.0.tgz"
@@ -1483,7 +1621,7 @@ get-proto@^1.0.1:
     dunder-proto "^1.0.1"
     es-object-atoms "^1.0.0"
 
-glob-parent@^5.1.2, glob-parent@~5.1.2:
+glob-parent@^5.1.2:
   version "5.1.2"
   resolved "https://registry.npmjs.org/glob-parent/-/glob-parent-5.1.2.tgz"
   integrity sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==
@@ -1497,6 +1635,13 @@ glob-parent@^6.0.2:
   dependencies:
     is-glob "^4.0.3"
 
+glob-parent@~5.1.2:
+  version "5.1.2"
+  resolved "https://registry.npmjs.org/glob-parent/-/glob-parent-5.1.2.tgz"
+  integrity sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==
+  dependencies:
+    is-glob "^4.0.1"
+
 gopd@^1.0.1, gopd@^1.2.0:
   version "1.2.0"
   resolved "https://registry.npmjs.org/gopd/-/gopd-1.2.0.tgz"
@@ -1507,6 +1652,11 @@ graceful-fs@^4.1.11:
   resolved "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz"
   integrity sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==
 
+has-flag@^4.0.0:
+  version "4.0.0"
+  resolved "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz"
+  integrity sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==
+
 has-property-descriptors@^1.0.0, has-property-descriptors@^1.0.2:
   version "1.0.2"
   resolved "https://registry.npmjs.org/has-property-descriptors/-/has-property-descriptors-1.0.2.tgz"
@@ -1568,6 +1718,11 @@ hmac-drbg@^1.0.1:
     minimalistic-assert "^1.0.0"
     minimalistic-crypto-utils "^1.0.1"
 
+html-escaper@^2.0.0:
+  version "2.0.2"
+  resolved "https://registry.npmjs.org/html-escaper/-/html-escaper-2.0.2.tgz"
+  integrity sha512-H2iMtd0I4Mt5eYiapRdIDjp+XzelXQ0tFE4JS7YFwFevXXMmOp9myNrUvCg0D6ws8iqkRPBfKHgbwig1SmlLfg==
+
 htmlparser2@^6.1.0:
   version "6.1.0"
   resolved "https://registry.npmjs.org/htmlparser2/-/htmlparser2-6.1.0.tgz"
@@ -1588,7 +1743,7 @@ ieee754@^1.1.13, ieee754@^1.2.1:
   resolved "https://registry.npmjs.org/ieee754/-/ieee754-1.2.1.tgz"
   integrity sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA==
 
-immer@^11.0.0:
+immer@^11.0.0, immer@>=9.0.6:
   version "11.1.3"
   resolved "https://registry.npmjs.org/immer/-/immer-11.1.3.tgz"
   integrity sha512-6jQTc5z0KJFtr1UgFpIL3N9XSC3saRaI9PwWtzM2pSqkNGtiNkYY2OSwkOGDK2XcTRcLb1pi/aNkKZz0nxVH4Q==
@@ -1708,6 +1863,28 @@ isomorphic-timers-promises@^1.0.1:
   resolved "https://registry.npmjs.org/isomorphic-timers-promises/-/isomorphic-timers-promises-1.0.1.tgz"
   integrity sha512-u4sej9B1LPSxTGKB/HiuzvEQnXH0ECYkSVQU39koSwmFAxhlEAFl9RdTvLv4TOTQUgBS5O3O5fwUxk6byBZ+IQ==
 
+istanbul-lib-coverage@^3.0.0, istanbul-lib-coverage@^3.2.2:
+  version "3.2.2"
+  resolved "https://registry.npmjs.org/istanbul-lib-coverage/-/istanbul-lib-coverage-3.2.2.tgz"
+  integrity sha512-O8dpsF+r0WV/8MNRKfnmrtCWhuKjxrq2w+jpzBL5UZKTi2LeVWnWOmWRxFlesJONmc+wLAGvKQZEOanko0LFTg==
+
+istanbul-lib-report@^3.0.0, istanbul-lib-report@^3.0.1:
+  version "3.0.1"
+  resolved "https://registry.npmjs.org/istanbul-lib-report/-/istanbul-lib-report-3.0.1.tgz"
+  integrity sha512-GCfE1mtsHGOELCU8e/Z7YWzpmybrx/+dSTfLrvY8qRmaY6zXTKWn6WQIjaAFw069icm6GVMNkgu0NzI4iPZUNw==
+  dependencies:
+    istanbul-lib-coverage "^3.0.0"
+    make-dir "^4.0.0"
+    supports-color "^7.1.0"
+
+istanbul-reports@^3.2.0:
+  version "3.2.0"
+  resolved "https://registry.npmjs.org/istanbul-reports/-/istanbul-reports-3.2.0.tgz"
+  integrity sha512-HGYWWS/ehqTV3xN10i23tkPkpH46MLCIMFNCaaKNavAXTF1RkqxawEPtnjnGZ6XKSInBKkiOA5BKS+aZiY3AvA==
+  dependencies:
+    html-escaper "^2.0.0"
+    istanbul-lib-report "^3.0.0"
+
 jiti@^1.21.7:
   version "1.21.7"
   resolved "https://registry.npmjs.org/jiti/-/jiti-1.21.7.tgz"
@@ -1718,6 +1895,11 @@ js-tokens@^4.0.0:
   resolved "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz"
   integrity sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==
 
+js-tokens@^9.0.1:
+  version "9.0.1"
+  resolved "https://registry.npmjs.org/js-tokens/-/js-tokens-9.0.1.tgz"
+  integrity sha512-mxa9E9ITFOt0ban3j6L5MpjwegGz6lBQmM1IJkWeBZGcMxto50+eWdjC/52xDbS2vy0k7vIMK0Fe2wfL9OQSpQ==
+
 jsesc@^3.0.2:
   version "3.1.0"
   resolved "https://registry.npmjs.org/jsesc/-/jsesc-3.1.0.tgz"
@@ -1764,13 +1946,29 @@ lru-cache@^5.1.1:
   dependencies:
     yallist "^3.0.2"
 
-magic-string@^0.30.3:
+magic-string@^0.30.21, magic-string@^0.30.3:
   version "0.30.21"
   resolved "https://registry.npmjs.org/magic-string/-/magic-string-0.30.21.tgz"
   integrity sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==
   dependencies:
     "@jridgewell/sourcemap-codec" "^1.5.5"
 
+magicast@^0.5.1:
+  version "0.5.1"
+  resolved "https://registry.npmjs.org/magicast/-/magicast-0.5.1.tgz"
+  integrity sha512-xrHS24IxaLrvuo613F719wvOIv9xPHFWQHuvGUBmPnCA/3MQxKI3b+r7n1jAoDHmsbC5bRhTZYR77invLAxVnw==
+  dependencies:
+    "@babel/parser" "^7.28.5"
+    "@babel/types" "^7.28.5"
+    source-map-js "^1.2.1"
+
+make-dir@^4.0.0:
+  version "4.0.0"
+  resolved "https://registry.npmjs.org/make-dir/-/make-dir-4.0.0.tgz"
+  integrity sha512-hXdUTZYIVOt1Ex//jAQi+wTZZpUpwBj/0QsOzqegb3rGMMeJiSEu5xLHnYfBrRV4RH2+OCSOO95Is/7x1WJ4bw==
+  dependencies:
+    semver "^7.5.3"
+
 math-intrinsics@^1.1.0:
   version "1.1.0"
   resolved "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz"
@@ -1826,16 +2024,16 @@ minimalistic-crypto-utils@^1.0.1:
   resolved "https://registry.npmjs.org/minimalistic-crypto-utils/-/minimalistic-crypto-utils-1.0.1.tgz"
   integrity sha512-JIYlbt6g8i5jKfJ3xz7rF0LXmv2TkDxBLUkiBeZ7bAx4GnnNMr8xFpGnOxn6GhTEHx3SjRrZEoU+j04prX1ktg==
 
-ms@2.0.0:
-  version "2.0.0"
-  resolved "https://registry.npmjs.org/ms/-/ms-2.0.0.tgz"
-  integrity sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A==
-
 ms@^2.1.3:
   version "2.1.3"
   resolved "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz"
   integrity sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==
 
+ms@2.0.0:
+  version "2.0.0"
+  resolved "https://registry.npmjs.org/ms/-/ms-2.0.0.tgz"
+  integrity sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A==
+
 mz@^2.7.0:
   version "2.7.0"
   resolved "https://registry.npmjs.org/mz/-/mz-2.7.0.tgz"
@@ -1950,6 +2148,11 @@ object.assign@^4.1.4:
     has-symbols "^1.1.0"
     object-keys "^1.1.1"
 
+obug@^2.1.1:
+  version "2.1.1"
+  resolved "https://registry.npmjs.org/obug/-/obug-2.1.1.tgz"
+  integrity sha512-uTqF9MuPraAQ+IsnPf366RG4cP9RtUi7MLO1N3KEc+wb0a6yKpeL0lmk2IB1jY5KHPAlTc6T/JRdC/YqxHNwkQ==
+
 os-browserify@^0.3.0:
   version "0.3.0"
   resolved "https://registry.npmjs.org/os-browserify/-/os-browserify-0.3.0.tgz"
@@ -2005,6 +2208,11 @@ path-parse@^1.0.7:
   resolved "https://registry.npmjs.org/path-parse/-/path-parse-1.0.7.tgz"
   integrity sha512-LDJzPVEEEPR+y48z93A0Ed0yXb8pAByGWo/k5YYdYgpY2/2EsOsksJrq7lOHxryrVOn1ejG6oAp8ahvOIQD8sw==
 
+pathe@^2.0.3:
+  version "2.0.3"
+  resolved "https://registry.npmjs.org/pathe/-/pathe-2.0.3.tgz"
+  integrity sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==
+
 pbkdf2@^3.1.2, pbkdf2@^3.1.5:
   version "3.1.5"
   resolved "https://registry.npmjs.org/pbkdf2/-/pbkdf2-3.1.5.tgz"
@@ -2022,12 +2230,22 @@ picocolors@^1.1.1:
   resolved "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz"
   integrity sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==
 
-picomatch@^2.0.4, picomatch@^2.2.1, picomatch@^2.3.1:
+picomatch@^2.0.4:
   version "2.3.1"
   resolved "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz"
   integrity sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==
 
-picomatch@^4.0.2, picomatch@^4.0.3:
+picomatch@^2.2.1:
+  version "2.3.1"
+  resolved "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz"
+  integrity sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==
+
+picomatch@^2.3.1:
+  version "2.3.1"
+  resolved "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz"
+  integrity sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==
+
+"picomatch@^3 || ^4", picomatch@^4.0.2, picomatch@^4.0.3:
   version "4.0.3"
   resolved "https://registry.npmjs.org/picomatch/-/picomatch-4.0.3.tgz"
   integrity sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==
@@ -2084,15 +2302,15 @@ postcss-nested@^6.2.0:
   dependencies:
     postcss-selector-parser "^6.1.1"
 
-postcss-selector-parser@6.0.10:
-  version "6.0.10"
-  resolved "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-6.0.10.tgz"
-  integrity sha512-IQ7TZdoaqbT+LCpShg46jnZVlhWD2w6iQYAcYXfHARZ7X1t/UGhhceQDs5X0cGqKvYlHNOuv7Oa1xmb0oQuA3w==
+postcss-selector-parser@^6.1.1:
+  version "6.1.2"
+  resolved "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-6.1.2.tgz"
+  integrity sha512-Q8qQfPiZ+THO/3ZrOrO0cJJKfpYCagtMUkXbnEfmgUjwXg6z/WBeOyS9APBBPCTSiDV+s4SwQGu8yFsiMRIudg==
   dependencies:
     cssesc "^3.0.0"
     util-deprecate "^1.0.2"
 
-postcss-selector-parser@^6.1.1, postcss-selector-parser@^6.1.2:
+postcss-selector-parser@^6.1.2:
   version "6.1.2"
   resolved "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-6.1.2.tgz"
   integrity sha512-Q8qQfPiZ+THO/3ZrOrO0cJJKfpYCagtMUkXbnEfmgUjwXg6z/WBeOyS9APBBPCTSiDV+s4SwQGu8yFsiMRIudg==
@@ -2100,12 +2318,20 @@ postcss-selector-parser@^6.1.1, postcss-selector-parser@^6.1.2:
     cssesc "^3.0.0"
     util-deprecate "^1.0.2"
 
+postcss-selector-parser@6.0.10:
+  version "6.0.10"
+  resolved "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-6.0.10.tgz"
+  integrity sha512-IQ7TZdoaqbT+LCpShg46jnZVlhWD2w6iQYAcYXfHARZ7X1t/UGhhceQDs5X0cGqKvYlHNOuv7Oa1xmb0oQuA3w==
+  dependencies:
+    cssesc "^3.0.0"
+    util-deprecate "^1.0.2"
+
 postcss-value-parser@^4.0.0, postcss-value-parser@^4.2.0:
   version "4.2.0"
   resolved "https://registry.npmjs.org/postcss-value-parser/-/postcss-value-parser-4.2.0.tgz"
   integrity sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ==
 
-postcss@^8.4.47, postcss@^8.5.6:
+postcss@^8.0.0, postcss@^8.1.0, postcss@^8.2.14, postcss@^8.4.21, postcss@^8.4.47, postcss@^8.5.6, postcss@>=8.0.9:
   version "8.5.6"
   resolved "https://registry.npmjs.org/postcss/-/postcss-8.5.6.tgz"
   integrity sha512-3Ybi1tAuwAP9s0r1UQ2J4n5Y0G05bJkpUIO0/bI9MhwmD70S5aTWbXGBwxHrelT+XM1k6dM0pk+SwNkpTRN7Pg==
@@ -2178,14 +2404,14 @@ randomfill@^1.0.4:
     randombytes "^2.0.5"
     safe-buffer "^5.1.0"
 
-react-dom@^19.1.0:
+"react-dom@^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", react-dom@^19.1.0, react-dom@>=18:
   version "19.2.4"
   resolved "https://registry.npmjs.org/react-dom/-/react-dom-19.2.4.tgz"
   integrity sha512-AXJdLo8kgMbimY95O2aKQqsz2iWi9jMgKJhRBAxECE4IFxfcazB2LmzloIoibJI3C12IlY20+KFaLv+71bUJeQ==
   dependencies:
     scheduler "^0.27.0"
 
-react-redux@^9.2.0:
+"react-redux@^7.2.1 || ^8.1.3 || ^9.0.0", react-redux@^9.2.0:
   version "9.2.0"
   resolved "https://registry.npmjs.org/react-redux/-/react-redux-9.2.0.tgz"
   integrity sha512-ROY9fvHhwOD9ySfrF0wmvu//bKCQ6AeZZq1nJNtbDC+kk5DuSuNX/n6YWYF/SYy7bSba4D4FSz8DJeKY/S/r+g==
@@ -2213,7 +2439,7 @@ react-router@7.13.0:
     cookie "^1.0.1"
     set-cookie-parser "^2.6.0"
 
-react@^19.1.0:
+"react@^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", "react@^16.9.0 || ^17.0.0 || ^18 || ^19", "react@^18.0 || ^19", react@^19.1.0, react@^19.2.4, react@>=18, react@>=18.0.0:
   version "19.2.4"
   resolved "https://registry.npmjs.org/react/-/react-19.2.4.tgz"
   integrity sha512-9nfp2hYpCwOjAN+8TZFGhtWEwgvWHXqESH8qT89AT/lWklpLON22Lc8pEtnpsZz7VmawabSU0gCjnj8aC0euHQ==
@@ -2276,7 +2502,7 @@ redux-thunk@^3.1.0:
   resolved "https://registry.npmjs.org/redux-thunk/-/redux-thunk-3.1.0.tgz"
   integrity sha512-NW2r5T6ksUKXCabzhL9z+h206HQw/NJkcLm1GPImRQ8IzfXwRGqjVhKJGauHirT0DAuyy6hjdnMZaRoAcy0Klw==
 
-redux@^5.0.0, redux@^5.0.1:
+redux@^5.0.0, redux@^5.0.1, redux@>4.0.0:
   version "5.0.1"
   resolved "https://registry.npmjs.org/redux/-/redux-5.0.1.tgz"
   integrity sha512-M9/ELqF6fy8FwmkpnF0S3YKOqMyoWJ4+CS5Efg2ct3oY9daQvd/Pc71FpGZsVsbl3Cpb+IIcjBDUnnyBdQbq4w==
@@ -2308,7 +2534,7 @@ ripemd160@^2.0.0, ripemd160@^2.0.1, ripemd160@^2.0.3:
     hash-base "^3.1.2"
     inherits "^2.0.4"
 
-rollup@^4.43.0:
+rollup@^1.20.0||^2.0.0||^3.0.0||^4.0.0, rollup@^4.43.0:
   version "4.56.0"
   resolved "https://registry.npmjs.org/rollup/-/rollup-4.56.0.tgz"
   integrity sha512-9FwVqlgUHzbXtDg9RCMgodF3Ua4Na6Gau+Sdt9vyCN4RhHfVKX2DCHy3BjMLTDd47ITDhYAnTwGulWTblJSDLg==
@@ -2354,7 +2580,12 @@ safe-buffer@^5.0.1, safe-buffer@^5.1.0, safe-buffer@^5.1.1, safe-buffer@^5.1.2,
   resolved "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz"
   integrity sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==
 
-safe-buffer@~5.1.0, safe-buffer@~5.1.1:
+safe-buffer@~5.1.0:
+  version "5.1.2"
+  resolved "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz"
+  integrity sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g==
+
+safe-buffer@~5.1.1:
   version "5.1.2"
   resolved "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz"
   integrity sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g==
@@ -2378,6 +2609,11 @@ semver@^6.3.1:
   resolved "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz"
   integrity sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==
 
+semver@^7.5.3:
+  version "7.7.3"
+  resolved "https://registry.npmjs.org/semver/-/semver-7.7.3.tgz"
+  integrity sha512-SdsKMrI9TdgjdweUSR9MweHA4EJ8YxHn8DFaDisvhVlUOe4BF1tLD7GAj0lIqWVl+dPb/rExr0Btby5loQm20Q==
+
 set-cookie-parser@^2.6.0:
   version "2.7.2"
   resolved "https://registry.npmjs.org/set-cookie-parser/-/set-cookie-parser-2.7.2.tgz"
@@ -2449,6 +2685,11 @@ side-channel@^1.1.0:
     side-channel-map "^1.0.1"
     side-channel-weakmap "^1.0.2"
 
+siginfo@^2.0.0:
+  version "2.0.0"
+  resolved "https://registry.npmjs.org/siginfo/-/siginfo-2.0.0.tgz"
+  integrity sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==
+
 slide@^1.1.5:
   version "1.1.6"
   resolved "https://registry.npmjs.org/slide/-/slide-1.1.6.tgz"
@@ -2490,6 +2731,16 @@ source-map-js@^1.2.1:
   resolved "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz"
   integrity sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==
 
+stackback@0.0.2:
+  version "0.0.2"
+  resolved "https://registry.npmjs.org/stackback/-/stackback-0.0.2.tgz"
+  integrity sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==
+
+std-env@^3.10.0:
+  version "3.10.0"
+  resolved "https://registry.npmjs.org/std-env/-/std-env-3.10.0.tgz"
+  integrity sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg==
+
 store2@^2.13.0:
   version "2.14.4"
   resolved "https://registry.npmjs.org/store2/-/store2-2.14.4.tgz"
@@ -2540,12 +2791,19 @@ sucrase@^3.35.0:
     tinyglobby "^0.2.11"
     ts-interface-checker "^0.1.9"
 
+supports-color@^7.1.0:
+  version "7.2.0"
+  resolved "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz"
+  integrity sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==
+  dependencies:
+    has-flag "^4.0.0"
+
 supports-preserve-symlinks-flag@^1.0.0:
   version "1.0.0"
   resolved "https://registry.npmjs.org/supports-preserve-symlinks-flag/-/supports-preserve-symlinks-flag-1.0.0.tgz"
   integrity sha512-ot0WnXS9fgdkgIcePe6RHNk1WA8+muPa6cSjeR3V8K27q9BB1rTE3R1p7Hv0z1ZyAc8s6Vvv8DIyWf681MAt0w==
 
-tailwindcss@^3.4.19:
+tailwindcss@^3.4.19, "tailwindcss@>=3.0.0 || >= 3.0.0-alpha.1 || >= 4.0.0-alpha.20 || >= 4.0.0-beta.1", "tailwindcss@>=3.0.0 || insiders || >=4.0.0-alpha.20 || >=4.0.0-beta.1":
   version "3.4.19"
   resolved "https://registry.npmjs.org/tailwindcss/-/tailwindcss-3.4.19.tgz"
   integrity sha512-3ofp+LL8E+pK/JuPLPggVAIaEuhvIz4qNcf3nA1Xn2o/7fb7s/TYpHhwGDv1ZU3PkBluUVaF8PyCHcm48cKLWQ==
@@ -2617,6 +2875,16 @@ timers-browserify@^2.0.4:
   dependencies:
     setimmediate "^1.0.4"
 
+tinybench@^2.9.0:
+  version "2.9.0"
+  resolved "https://registry.npmjs.org/tinybench/-/tinybench-2.9.0.tgz"
+  integrity sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==
+
+tinyexec@^1.0.2:
+  version "1.0.2"
+  resolved "https://registry.npmjs.org/tinyexec/-/tinyexec-1.0.2.tgz"
+  integrity sha512-W/KYk+NFhkmsYpuHq5JykngiOCnxeVL8v8dFnqxSD8qEEdRfXk1SDM6JzNqcERbcGYj9tMrDQBYV9cjgnunFIg==
+
 tinyglobby@^0.2.11, tinyglobby@^0.2.15:
   version "0.2.15"
   resolved "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.15.tgz"
@@ -2625,6 +2893,11 @@ tinyglobby@^0.2.11, tinyglobby@^0.2.15:
     fdir "^6.5.0"
     picomatch "^4.0.3"
 
+tinyrainbow@^3.0.3:
+  version "3.0.3"
+  resolved "https://registry.npmjs.org/tinyrainbow/-/tinyrainbow-3.0.3.tgz"
+  integrity sha512-PSkbLUoxOFRzJYjjxHJt9xro7D+iilgMX/C9lawzVuYiIdcihh9DXmVibBe8lmcFrRi/VzlPjBxbN7rH24q8/Q==
+
 to-buffer@^1.2.0, to-buffer@^1.2.1, to-buffer@^1.2.2:
   version "1.2.2"
   resolved "https://registry.npmjs.org/to-buffer/-/to-buffer-1.2.2.tgz"
@@ -2708,12 +2981,12 @@ url@^0.11.4:
     punycode "^1.4.1"
     qs "^6.12.3"
 
-use-sync-external-store@^1.4.0:
+use-sync-external-store@^1.4.0, use-sync-external-store@>=1.2.0:
   version "1.6.0"
   resolved "https://registry.npmjs.org/use-sync-external-store/-/use-sync-external-store-1.6.0.tgz"
   integrity sha512-Pp6GSwGP/NrPIrxVFAIkOQeyw8lFenOHijQWkUTrDvrF4ALqylP2C/KCkeS9dpUM3KvYRQhna5vt7IL95+ZQ9w==
 
-utf-8-validate@^5.0.2, utf-8-validate@^5.0.5:
+utf-8-validate@^5.0.2, utf-8-validate@^5.0.5, utf-8-validate@>=5.0.2:
   version "5.0.10"
   resolved "https://registry.npmjs.org/utf-8-validate/-/utf-8-validate-5.0.10.tgz"
   integrity sha512-Z6czzLq4u8fPOyx7TU6X3dvUZVvoJmxSQ+IcrlmagKhilxlhZgxPK6C5Jqbkw1IDUmFTM+cz9QDnnLTwDz/2gQ==
@@ -2744,7 +3017,7 @@ vite-plugin-node-polyfills@^0.25.0:
     "@rollup/plugin-inject" "^5.0.5"
     node-stdlib-browser "^1.3.1"
 
-vite@^7.0.4:
+"vite@^2.0.0 || ^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0", "vite@^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0", "vite@^6.0.0 || ^7.0.0", "vite@^6.0.0 || ^7.0.0-0", vite@^7.0.4:
   version "7.3.1"
   resolved "https://registry.npmjs.org/vite/-/vite-7.3.1.tgz"
   integrity sha512-w+N7Hifpc3gRjZ63vYBXA56dvvRlNWRczTdmCBBa+CotUzAPf5b7YMdMR/8CQoeYE5LX3W4wj6RYTgonm1b9DA==
@@ -2758,6 +3031,32 @@ vite@^7.0.4:
   optionalDependencies:
     fsevents "~2.3.3"
 
+vitest@^4.0.18, vitest@4.0.18:
+  version "4.0.18"
+  resolved "https://registry.npmjs.org/vitest/-/vitest-4.0.18.tgz"
+  integrity sha512-hOQuK7h0FGKgBAas7v0mSAsnvrIgAvWmRFjmzpJ7SwFHH3g1k2u37JtYwOwmEKhK6ZO3v9ggDBBm0La1LCK4uQ==
+  dependencies:
+    "@vitest/expect" "4.0.18"
+    "@vitest/mocker" "4.0.18"
+    "@vitest/pretty-format" "4.0.18"
+    "@vitest/runner" "4.0.18"
+    "@vitest/snapshot" "4.0.18"
+    "@vitest/spy" "4.0.18"
+    "@vitest/utils" "4.0.18"
+    es-module-lexer "^1.7.0"
+    expect-type "^1.2.2"
+    magic-string "^0.30.21"
+    obug "^2.1.1"
+    pathe "^2.0.3"
+    picomatch "^4.0.3"
+    std-env "^3.10.0"
+    tinybench "^2.9.0"
+    tinyexec "^1.0.2"
+    tinyglobby "^0.2.15"
+    tinyrainbow "^3.0.3"
+    vite "^6.0.0 || ^7.0.0"
+    why-is-node-running "^2.3.0"
+
 vm-browserify@^1.0.1:
   version "1.1.2"
   resolved "https://registry.npmjs.org/vm-browserify/-/vm-browserify-1.1.2.tgz"
@@ -2788,6 +3087,14 @@ which-typed-array@^1.1.16, which-typed-array@^1.1.2:
     gopd "^1.2.0"
     has-tostringtag "^1.0.2"
 
+why-is-node-running@^2.3.0:
+  version "2.3.0"
+  resolved "https://registry.npmjs.org/why-is-node-running/-/why-is-node-running-2.3.0.tgz"
+  integrity sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==
+  dependencies:
+    siginfo "^2.0.0"
+    stackback "0.0.2"
+
 write-file-atomic@^1.1.4:
   version "1.3.4"
   resolved "https://registry.npmjs.org/write-file-atomic/-/write-file-atomic-1.3.4.tgz"