From 23328bf5d2b3a596c093262b5ddde0da50ecde47 Mon Sep 17 00:00:00 2001
From: kirrrrusha <kirilllebedenko@gmail.com>
Date: Sun, 14 Sep 2025 13:55:02 +0300
Subject: [PATCH] chore: update docs

---
 .cursorrules                                  |  68 ++++
 ARCHITECTURE_DIAGRAMS.md                      | 327 +++++++++++++++
 CURSOR_GUIDE.md                               | 255 ++++++++++++
 CURSOR_IMPROVEMENTS.md                        | 142 +++++++
 DEVELOPER_GUIDE.md                            | 375 ++++++++++++++++++
 DOCS_STRUCTURE.md                             | 194 +++++++++
 PROJECT_MAP.md                                | 204 ++++++++++
 README.md                                     | 213 +++++++---
 README.ru.md                                  | 241 +++++++++++
 src/background.ts                             |  12 +
 .../request-profile/model/request-profiles.ts |  33 ++
 11 files changed, 2007 insertions(+), 57 deletions(-)
 create mode 100644 .cursorrules
 create mode 100644 ARCHITECTURE_DIAGRAMS.md
 create mode 100644 CURSOR_GUIDE.md
 create mode 100644 CURSOR_IMPROVEMENTS.md
 create mode 100644 DEVELOPER_GUIDE.md
 create mode 100644 DOCS_STRUCTURE.md
 create mode 100644 PROJECT_MAP.md
 create mode 100644 README.ru.md

diff --git a/.cursorrules b/.cursorrules
new file mode 100644
index 0000000..e8b7808
--- /dev/null
+++ b/.cursorrules
@@ -0,0 +1,68 @@
+# Правила для Cursor AI в проекте Cloudhood
+
+## Контекст проекта
+Cloudhood - это браузерное расширение для управления HTTP заголовками запросов, построенное на React + TypeScript + Effector с архитектурой Feature-Sliced Design.
+
+## Архитектура
+- **Feature-Sliced Design (FSD)**: Строго следуйте правилам импортов между слоями
+- **Effector**: Используется для управления состоянием (stores, events, effects)
+- **React**: UI компоненты с хуками useUnit для подключения к Effector
+- **Chrome Extension API**: Declarative Net Request для управления заголовками
+
+## Структура проекта
+```
+src/
+├── app/          # Инициализация приложения
+├── pages/        # Страницы (композиция виджетов)
+├── widgets/      # UI блоки высокого уровня
+├── features/     # Пользовательские функции
+├── entities/     # Бизнес-сущности
+└── shared/       # Общие ресурсы
+```
+
+## Правила импортов FSD
+- Можно импортировать только из нижележащих слоев
+- Нельзя импортировать из вышележащих слоев
+- Горизонтальные импорты только через shared
+- Используйте алиасы путей: #app, #pages, #widgets, #features, #entities, #shared
+
+## Паттерны Effector
+- Stores: `$` префикс (например, `$requestProfiles`)
+- Events: `createEvent()` для действий пользователя
+- Effects: `createEffect()` для асинхронных операций
+- Sample: для реактивности между stores и events
+- Attach: для эффектов с параметрами
+
+## Стиль кода
+- Используйте TypeScript строго
+- Добавляйте комментарии к сложной логике
+- Следуйте существующим паттернам в проекте
+- Используйте Emotion для стилизации
+- Логируйте важные операции через logger
+
+## Часто используемые запросы
+- "Как работает Feature-Sliced Design в этом проекте?"
+- "Покажи все Effector stores в проекте"
+- "Где обрабатываются HTTP заголовки?"
+- "Как добавить новую функцию в архитектуру FSD?"
+
+## Тестирование
+- Unit тесты для утилит в shared/utils/__tests__/
+- E2E тесты в tests/e2e/ с Playwright
+- Запуск: `pnpm test:unit` и `pnpm test:e2e`
+
+## Сборка
+- Chrome: `pnpm dev:chrome` / `pnpm build:chromium`
+- Firefox: `pnpm dev:firefox` / `pnpm build:firefox`
+- Все браузеры: `pnpm build`
+
+## Отладка
+- Используйте logger из shared/utils/logger
+- Chrome DevTools для Service Worker и Popup
+- Firefox DevTools через about:debugging
+
+## Документация
+- PROJECT_MAP.md - подробная карта проекта
+- CURSOR_GUIDE.md - руководство по работе с Cursor
+- ARCHITECTURE_DIAGRAMS.md - диаграммы архитектуры
+- DEVELOPER_GUIDE.md - руководство разработчика
diff --git a/ARCHITECTURE_DIAGRAMS.md b/ARCHITECTURE_DIAGRAMS.md
new file mode 100644
index 0000000..81d4824
--- /dev/null
+++ b/ARCHITECTURE_DIAGRAMS.md
@@ -0,0 +1,327 @@
+# 🏗️ Диаграмма архитектуры Cloudhood
+
+## Общая архитектура проекта
+
+```mermaid
+graph TB
+    subgraph "Browser Extension"
+        SW[Service Worker<br/>background.ts]
+        POPUP[Popup UI<br/>React App]
+    end
+
+    subgraph "React Application"
+        APP[App.tsx]
+        MAIN[Main Page]
+
+        subgraph "Widgets Layer"
+            HEADER[Header Widget]
+            SIDEBAR[Sidebar Widget]
+            HEADERS[Request Headers Widget]
+            MODALS[Modals Widget]
+        end
+
+        subgraph "Features Layer"
+            EXPORT[Export Profile]
+            IMPORT[Import Profile]
+            COPY[Copy Headers]
+            CRUD[CRUD Headers]
+        end
+
+        subgraph "Entities Layer"
+            PROFILE[Request Profile]
+            NOTIFICATION[Notification]
+            MODAL[Modal State]
+            PAUSE[Pause State]
+        end
+
+        subgraph "Shared Layer"
+            UTILS[Utils]
+            COMPONENTS[Components]
+            ASSETS[Assets]
+        end
+    end
+
+    subgraph "External APIs"
+        CHROME[Chrome Extension API]
+        STORAGE[Chrome Storage]
+        NET[Declarative Net Request]
+    end
+
+    %% Connections
+    SW --> CHROME
+    SW --> STORAGE
+    SW --> NET
+
+    APP --> MAIN
+    MAIN --> HEADER
+    MAIN --> SIDEBAR
+    MAIN --> HEADERS
+    MAIN --> MODALS
+
+    HEADER --> EXPORT
+    HEADER --> COPY
+    SIDEBAR --> PROFILE
+    HEADERS --> CRUD
+    MODALS --> IMPORT
+
+    EXPORT --> PROFILE
+    IMPORT --> PROFILE
+    COPY --> PROFILE
+    CRUD --> PROFILE
+
+    PROFILE --> STORAGE
+    NOTIFICATION --> CHROME
+    MODAL --> COMPONENTS
+    PAUSE --> STORAGE
+
+    UTILS --> CHROME
+    UTILS --> STORAGE
+    COMPONENTS --> ASSETS
+```
+
+## Поток данных Effector
+
+```mermaid
+graph LR
+    subgraph "User Actions"
+        UI[UI Components]
+    end
+
+    subgraph "Effector Events"
+        EVENTS[Events<br/>createEvent]
+    end
+
+    subgraph "Effector Stores"
+        STORES[Stores<br/>createStore]
+    end
+
+    subgraph "Effects"
+        EFFECTS[Effects<br/>createEffect]
+    end
+
+    subgraph "External APIs"
+        API[Chrome API<br/>Storage API]
+    end
+
+    UI --> EVENTS
+    EVENTS --> STORES
+    EVENTS --> EFFECTS
+    STORES --> UI
+    EFFECTS --> API
+    API --> STORES
+```
+
+## Структура Feature-Sliced Design
+
+```mermaid
+graph TD
+    subgraph "App Layer"
+        A[App.tsx<br/>Инициализация]
+    end
+
+    subgraph "Pages Layer"
+        P[Main Page<br/>Композиция виджетов]
+    end
+
+    subgraph "Widgets Layer"
+        W1[Header<br/>Управление профилями]
+        W2[Sidebar<br/>Список профилей]
+        W3[Request Headers<br/>Редактирование]
+        W4[Modals<br/>Диалоги]
+    end
+
+    subgraph "Features Layer"
+        F1[Export Profile<br/>Экспорт данных]
+        F2[Import Profile<br/>Импорт данных]
+        F3[Copy Headers<br/>Копирование]
+        F4[CRUD Headers<br/>Управление заголовками]
+    end
+
+    subgraph "Entities Layer"
+        E1[Request Profile<br/>Основная сущность]
+        E2[Notification<br/>Уведомления]
+        E3[Modal<br/>Состояние модалок]
+        E4[Pause<br/>Состояние паузы]
+    end
+
+    subgraph "Shared Layer"
+        S1[Utils<br/>Утилиты]
+        S2[Components<br/>Компоненты]
+        S3[Assets<br/>Ресурсы]
+        S4[Constants<br/>Константы]
+    end
+
+    %% Dependencies (only lower layers can import from higher layers)
+    A --> P
+    P --> W1
+    P --> W2
+    P --> W3
+    P --> W4
+
+    W1 --> F1
+    W1 --> F3
+    W2 --> E1
+    W3 --> F4
+    W4 --> F2
+
+    F1 --> E1
+    F2 --> E1
+    F3 --> E1
+    F4 --> E1
+
+    F1 --> S1
+    F2 --> S1
+    F3 --> S1
+    F4 --> S1
+
+    E1 --> S1
+    E2 --> S1
+    E3 --> S1
+    E4 --> S1
+
+    W1 --> S2
+    W2 --> S2
+    W3 --> S2
+    W4 --> S2
+```
+
+## Интеграция с Chrome Extension API
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant UI as React UI
+    participant SW as Service Worker
+    participant API as Chrome API
+    participant WEB as Web Page
+
+    U->>UI: Изменяет профиль
+    UI->>SW: Сохраняет в storage
+    SW->>API: Обновляет Declarative Net Request
+    API->>WEB: Применяет заголовки к запросам
+
+    Note over SW,API: Автоматическое применение<br/>заголовков ко всем запросам
+
+    U->>UI: Переключает профиль
+    UI->>SW: Обновляет selected profile
+    SW->>API: Перезагружает правила
+    API->>WEB: Применяет новые заголовки
+```
+
+## Управление состоянием Effector
+
+```mermaid
+stateDiagram-v2
+    [*] --> Initializing
+
+    Initializing --> LoadingProfiles: initApp()
+    LoadingProfiles --> ProfilesLoaded: loadProfiles()
+
+    ProfilesLoaded --> ProfileSelected: selectProfile()
+    ProfileSelected --> HeadersModified: modifyHeaders()
+    HeadersModified --> HeadersSaved: saveHeaders()
+    HeadersSaved --> ProfileSelected
+
+    ProfileSelected --> ProfileExported: exportProfile()
+    ProfileExported --> ProfileSelected
+
+    ProfileSelected --> ProfileImported: importProfile()
+    ProfileImported --> ProfilesLoaded
+
+    ProfileSelected --> ProfileDeleted: deleteProfile()
+    ProfileDeleted --> ProfilesLoaded
+
+    ProfilesLoaded --> Paused: pauseAll()
+    Paused --> ProfilesLoaded: resumeAll()
+
+    ProfilesLoaded --> [*]: Extension closed
+```
+
+## Компонентная архитектура UI
+
+```mermaid
+graph TB
+    subgraph "Main Page"
+        MP[MainPage]
+    end
+
+    subgraph "Header Widget"
+        H[Header]
+        H1[ProfileNameField]
+        H2[PauseAllRequestHeaders]
+        H3[CopyActiveRequestHeaders]
+    end
+
+    subgraph "Sidebar Widget"
+        S[Sidebar]
+        S1[SetRequestProfile]
+    end
+
+    subgraph "Request Headers Widget"
+        RH[RequestHeaders]
+        RH1[RequestHeaderRow]
+    end
+
+    subgraph "Modals Widget"
+        M[Modals]
+        M1[ExportModal]
+        M2[ImportModal]
+        M3[ImportFromExtensionModal]
+    end
+
+    MP --> H
+    MP --> S
+    MP --> RH
+    MP --> M
+
+    H --> H1
+    H --> H2
+    H --> H3
+
+    S --> S1
+
+    RH --> RH1
+
+    M --> M1
+    M --> M2
+    M --> M3
+```
+
+## Поток данных при изменении заголовков
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant RH as RequestHeaders Widget
+    participant CRUD as CRUD Feature
+    participant PROFILE as Profile Entity
+    participant SW as Service Worker
+    participant API as Chrome API
+
+    U->>RH: Редактирует заголовок
+    RH->>CRUD: updateHeader()
+    CRUD->>PROFILE: updateHeaderEvent()
+    PROFILE->>PROFILE: Обновляет store
+    PROFILE->>SW: Сохраняет в storage
+    SW->>API: Обновляет Declarative Net Request
+    API-->>U: Заголовки применены к новым запросам
+```
+
+---
+
+## 📊 Статистика проекта
+
+- **Общее количество файлов**: ~150
+- **Строки кода**: ~15,000
+- **TypeScript файлы**: ~120
+- **React компоненты**: ~25
+- **Effector stores**: ~15
+- **Effector events**: ~30
+- **Утилиты**: ~20
+
+## 🎯 Ключевые метрики
+
+- **Покрытие тестами**: Unit tests для утилит, E2E для основных сценариев
+- **Производительность**: Ленивая загрузка модальных окон
+- **Размер бандла**: Оптимизирован для расширений браузера
+- **Совместимость**: Chrome + Firefox через polyfill
diff --git a/CURSOR_GUIDE.md b/CURSOR_GUIDE.md
new file mode 100644
index 0000000..605e3d0
--- /dev/null
+++ b/CURSOR_GUIDE.md
@@ -0,0 +1,255 @@
+# 🎯 Руководство по работе с Cursor для проекта Cloudhood
+
+## Обзор
+Это руководство поможет эффективно работать с проектом Cloudhood в Cursor IDE, используя возможности AI-ассистента для понимания архитектуры, поиска кода и разработки.
+
+## 🗂️ Структура проекта для Cursor
+
+### Ключевые директории для понимания
+```
+src/
+├── entities/          # 🏗️ Бизнес-сущности (основа архитектуры)
+├── features/          # ⚡ Пользовательские функции
+├── widgets/           # 🧩 UI компоненты высокого уровня
+├── pages/             # 📄 Страницы приложения
+├── shared/            # 🔧 Общие утилиты и компоненты
+└── background.ts      # 🔄 Service Worker расширения
+```
+
+## 🔍 Поиск и навигация в Cursor
+
+### Часто используемые запросы для поиска
+
+#### Поиск по функциональности
+```
+# Поиск логики профилей
+"request profile" OR "профиль" в entities/request-profile/
+
+# Поиск управления заголовками
+"request headers" OR "заголовки" в features/selected-profile-request-headers/
+
+# Поиск UI компонентов
+"header" OR "sidebar" в widgets/
+
+# Поиск утилит
+"browser API" OR "storage" в shared/utils/
+```
+
+#### Поиск по архитектурным слоям
+```
+# Поиск бизнес-логики
+"effector" OR "createEvent" OR "createStore" в entities/ и features/
+
+# Поиск UI компонентов
+"React" OR "useState" OR "useEffect" в widgets/ и pages/
+
+# Поиск интеграций
+"chrome" OR "browser" в background.ts и shared/utils/
+```
+
+### Контекстные запросы для AI
+
+#### Для понимания архитектуры
+```
+"Объясни архитектуру проекта Cloudhood"
+"Как работает Feature-Sliced Design в этом проекте?"
+"Покажи связи между entities, features и widgets"
+```
+
+#### Для поиска конкретной функциональности
+```
+"Где обрабатываются HTTP заголовки?"
+"Как работает экспорт профилей?"
+"Где настраивается Service Worker?"
+```
+
+#### Для разработки новых функций
+```
+"Как добавить новую функцию в архитектуру FSD?"
+"Где создать новый UI компонент?"
+"Как интегрировать с Chrome Extension API?"
+```
+
+## 📋 Шаблоны для создания компонентов
+
+### Создание новой Feature
+```typescript
+// features/new-feature/model.ts
+import { createEvent, createStore } from 'effector';
+
+export const newFeatureEvent = createEvent<string>();
+export const $newFeatureStore = createStore<string>('');
+
+$newFeatureStore.on(newFeatureEvent, (_, payload) => payload);
+```
+
+### Создание нового Widget
+```typescript
+// widgets/new-widget/NewWidget.tsx
+import { useUnit } from 'effector-react';
+import { $newFeatureStore } from '#features/new-feature/model';
+
+export function NewWidget() {
+  const [value] = useUnit([$newFeatureStore]);
+
+  return <div>{value}</div>;
+}
+```
+
+### Создание новой Entity
+```typescript
+// entities/new-entity/model.ts
+import { createEvent, createStore } from 'effector';
+
+export interface NewEntity {
+  id: string;
+  name: string;
+}
+
+export const $newEntityStore = createStore<NewEntity[]>([]);
+export const addNewEntity = createEvent<NewEntity>();
+```
+
+## 🛠️ Полезные команды Cursor
+
+### Поиск по коду
+- `Cmd+Shift+F` - глобальный поиск
+- `Cmd+P` - быстрый переход к файлу
+- `Cmd+Shift+O` - поиск символов в файле
+
+### AI-ассистент
+- `Cmd+K` - открыть AI чат
+- `Cmd+L` - объяснить выделенный код
+- `Cmd+I` - инлайн редактирование с AI
+
+### Рефакторинг
+- `F2` - переименование символа
+- `Cmd+Shift+R` - рефакторинг в области видимости
+- `Cmd+.` - быстрые исправления
+
+## 🎯 Специфичные для проекта запросы
+
+### Понимание Effector архитектуры
+```
+"Покажи все Effector stores в проекте"
+"Как связаны events и stores в request-profile?"
+"Где используется useUnit hook?"
+```
+
+### Работа с Chrome Extension API
+```
+"Как работает Declarative Net Request?"
+"Где настраиваются permissions в manifest?"
+"Как работает Service Worker в background.ts?"
+```
+
+### UI компоненты и стилизация
+```
+"Какие компоненты из @snack-uikit используются?"
+"Как настроена темизация в проекте?"
+"Где определены цвета профилей?"
+```
+
+## 📚 Контекстные подсказки для AI
+
+### При работе с новым кодом
+```
+"Этот код следует архитектуре Feature-Sliced Design?"
+"Какой слой FSD подходит для этой функциональности?"
+"Есть ли аналогичная логика в проекте?"
+```
+
+### При отладке
+```
+"Где может быть ошибка в этой цепочке вызовов?"
+"Как проверить состояние Effector store?"
+"Какие логи помогают отладить проблему?"
+```
+
+### При оптимизации
+```
+"Можно ли оптимизировать этот компонент?"
+"Есть ли дублирование кода в проекте?"
+"Как улучшить производительность этого кода?"
+```
+
+## 🔧 Настройка Cursor для проекта
+
+### Рекомендуемые расширения
+- **TypeScript Importer** - автоимпорт TypeScript модулей
+- **Auto Rename Tag** - синхронное переименование тегов
+- **Bracket Pair Colorizer** - цветные скобки
+- **GitLens** - расширенная Git интеграция
+
+### Настройки workspace
+```json
+{
+  "typescript.preferences.includePackageJsonAutoImports": "on",
+  "typescript.suggest.autoImports": true,
+  "editor.codeActionsOnSave": {
+    "source.organizeImports": true,
+    "source.fixAll.eslint": true
+  },
+  "search.exclude": {
+    "**/node_modules": true,
+    "**/build": true,
+    "**/dist": true
+  }
+}
+```
+
+## 🚀 Быстрые действия
+
+### Создание нового профиля
+1. Найти `entities/request-profile/model/`
+2. Изучить существующие stores и events
+3. Создать аналогичную структуру для нового типа профиля
+
+### Добавление нового заголовка
+1. Найти `features/selected-profile-request-headers/`
+2. Изучить CRUD операции
+3. Добавить новую операцию по аналогии
+
+### Создание нового модального окна
+1. Найти `widgets/modals/components/`
+2. Изучить существующие модальные окна
+3. Создать новый компонент по шаблону
+
+## 🐛 Отладка и диагностика
+
+### Поиск ошибок
+```
+"Где может быть ошибка с Chrome Extension API?"
+"Как проверить работу Service Worker?"
+"Где логируются ошибки в проекте?"
+```
+
+### Анализ производительности
+```
+"Где могут быть узкие места в производительности?"
+"Как оптимизировать рендеринг списков?"
+"Есть ли проблемы с памятью в Effector stores?"
+```
+
+## 📖 Дополнительные ресурсы
+
+### Документация технологий
+- [Effector](https://effector.dev/) - управление состоянием
+- [Feature-Sliced Design](https://feature-sliced.design/) - архитектура
+- [Chrome Extensions](https://developer.chrome.com/docs/extensions/) - API расширений
+- [Playwright](https://playwright.dev/) - E2E тестирование
+
+### Внутренние ресурсы
+- `PROJECT_MAP.md` - подробная карта проекта
+- `README.md` - общая информация о проекте
+- `RELEASE_SETUP.md` - настройка релизов
+
+---
+
+## 💡 Советы по эффективной работе
+
+1. **Начинайте с архитектуры** - понимайте слой FSD перед написанием кода
+2. **Используйте поиск по контексту** - ищите аналогичную функциональность
+3. **Следуйте паттернам** - используйте существующие паттерны Effector
+4. **Тестируйте изменения** - запускайте unit и E2E тесты
+5. **Документируйте сложную логику** - добавляйте комментарии к неочевидному коду
diff --git a/CURSOR_IMPROVEMENTS.md b/CURSOR_IMPROVEMENTS.md
new file mode 100644
index 0000000..e5ca981
--- /dev/null
+++ b/CURSOR_IMPROVEMENTS.md
@@ -0,0 +1,142 @@
+# 🎯 Итоговые рекомендации по улучшению проекта Cloudhood для работы с Cursor
+
+## ✅ Что было сделано
+
+### 1. 📋 Карта проекта (`PROJECT_MAP.md`)
+- **Создана подробная карта архитектуры** с описанием всех слоев FSD
+- **Документированы ключевые компоненты** и их назначение
+- **Описаны потоки данных** и интеграции с Chrome API
+- **Добавлены статистики проекта** и метрики
+
+### 2. 🎯 Руководство по Cursor (`CURSOR_GUIDE.md`)
+- **Специфичные запросы для AI** для понимания архитектуры
+- **Шаблоны для создания компонентов** по паттернам проекта
+- **Полезные команды Cursor** для навигации и поиска
+- **Контекстные подсказки** для эффективной работы с AI
+
+### 3. 🏗️ Диаграммы архитектуры (`ARCHITECTURE_DIAGRAMS.md`)
+- **Mermaid диаграммы** общей архитектуры проекта
+- **Схемы потоков данных** Effector
+- **Диаграммы FSD структуры** с зависимостями
+- **Sequence диаграммы** интеграции с Chrome API
+
+### 4. 👨‍💻 Руководство разработчика (`DEVELOPER_GUIDE.md`)
+- **Быстрый старт** для новых разработчиков
+- **Подробное описание архитектуры** FSD и Effector
+- **Примеры кода** и паттерны
+- **Инструкции по тестированию** и отладке
+
+### 5. 🔧 Настройки Cursor (`.cursorrules`)
+- **Правила для AI** с контекстом проекта
+- **Часто используемые запросы** для быстрого поиска
+- **Паттерны кода** и архитектурные принципы
+
+### 6. 📝 Улучшенная документация
+- **Комментарии к ключевым файлам** (background.ts, request-profiles.ts)
+- **Обновленный README** с ссылками на документацию
+- **Структурированная информация** для быстрого понимания
+
+## 🚀 Дополнительные рекомендации
+
+### Для дальнейшего улучшения проекта:
+
+#### 1. 📊 Добавить метрики и аналитику
+```typescript
+// shared/utils/analytics.ts
+export const trackUserAction = (action: string, data?: any) => {
+  // Отслеживание использования функций
+};
+```
+
+#### 2. 🧪 Расширить тестовое покрытие
+- Добавить тесты для Effector stores
+- Создать интеграционные тесты для Chrome API
+- Добавить тесты производительности
+
+#### 3. 📚 Создать Storybook
+```bash
+# Для документирования UI компонентов
+npx storybook@latest init
+```
+
+#### 4. 🔍 Добавить больше типов
+```typescript
+// shared/types/api.ts
+export interface ChromeExtensionAPI {
+  // Типизация Chrome Extension API
+}
+```
+
+#### 5. 🎨 Создать дизайн-систему
+```typescript
+// shared/design-system/
+├── tokens/
+├── components/
+└── themes/
+```
+
+#### 6. 📱 Добавить поддержку мобильных браузеров
+- Адаптация для Safari
+- Поддержка Edge
+- Оптимизация для мобильных устройств
+
+#### 7. 🔐 Улучшить безопасность
+- CSP политики
+- Валидация входных данных
+- Санитизация данных
+
+#### 8. ⚡ Оптимизация производительности
+- Ленивая загрузка компонентов
+- Мемоизация вычислений
+- Оптимизация бандла
+
+## 🎯 Как использовать созданную документацию
+
+### Для новых разработчиков:
+1. **Начните с `PROJECT_MAP.md`** - изучите общую архитектуру
+2. **Прочитайте `DEVELOPER_GUIDE.md`** - настройте окружение
+3. **Используйте `CURSOR_GUIDE.md`** - эффективно работайте с AI
+4. **Изучите `ARCHITECTURE_DIAGRAMS.md`** - понимайте потоки данных
+
+### Для работы с Cursor:
+1. **Используйте `.cursorrules`** - AI будет понимать контекст проекта
+2. **Применяйте запросы из `CURSOR_GUIDE.md`** - быстро находите нужный код
+3. **Следуйте шаблонам** - создавайте компоненты по паттернам проекта
+4. **Используйте диаграммы** - визуализируйте архитектуру
+
+### Для команды:
+1. **Документируйте изменения** - обновляйте документацию
+2. **Следуйте архитектуре FSD** - не нарушайте правила импортов
+3. **Тестируйте изменения** - запускайте unit и E2E тесты
+4. **Используйте логирование** - добавляйте логи для отладки
+
+## 📈 Ожидаемые результаты
+
+### Улучшение производительности разработки:
+- **Быстрое понимание архитектуры** новых разработчиками
+- **Эффективный поиск кода** с помощью AI
+- **Снижение времени на онбординг** с 2-3 дней до нескольких часов
+- **Уменьшение ошибок** благодаря пониманию паттернов
+
+### Улучшение качества кода:
+- **Следование архитектурным принципам** FSD
+- **Консистентность стиля кода** в команде
+- **Лучшее тестовое покрытие** благодаря пониманию структуры
+- **Быстрая отладка** с помощью документации
+
+### Улучшение работы с Cursor:
+- **Точные ответы AI** благодаря контексту проекта
+- **Быстрый поиск функций** с помощью специфичных запросов
+- **Автоматическое следование паттернам** проекта
+- **Эффективная навигация** по кодовой базе
+
+## 🎉 Заключение
+
+Созданная документация значительно улучшит работу с проектом Cloudhood в Cursor IDE. Разработчики смогут:
+
+- **Быстро понимать архитектуру** проекта
+- **Эффективно использовать AI** для поиска и создания кода
+- **Следовать лучшим практикам** разработки
+- **Минимизировать время на изучение** кодовой базы
+
+Документация покрывает все аспекты работы с проектом - от быстрого старта до продвинутых техник работы с Cursor AI.
diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md
new file mode 100644
index 0000000..5d8f98a
--- /dev/null
+++ b/DEVELOPER_GUIDE.md
@@ -0,0 +1,375 @@
+# 👨‍💻 Руководство разработчика Cloudhood
+
+## Обзор
+Это руководство поможет разработчикам быстро освоиться с проектом Cloudhood и эффективно работать с кодом.
+
+## 🚀 Быстрый старт
+
+### Предварительные требования
+- Node.js >= 20.0.0
+- pnpm >= 10.10.0
+- Chrome или Firefox для тестирования
+
+### Установка и запуск
+```bash
+# Клонирование репозитория
+git clone <repository-url>
+cd cloudhood
+
+# Установка зависимостей
+pnpm install
+
+# Запуск в режиме разработки для Chrome
+pnpm dev:chrome
+
+# Запуск в режиме разработки для Firefox
+pnpm dev:firefox
+```
+
+### Загрузка расширения в браузер
+
+#### Chrome
+1. Откройте `chrome://extensions/`
+2. Включите "Режим разработчика"
+3. Нажмите "Загрузить распакованное расширение"
+4. Выберите папку `build/chrome`
+
+#### Firefox
+1. Откройте `about:debugging`
+2. Нажмите "Этот Firefox"
+3. Нажмите "Загрузить временное дополнение"
+4. Выберите файл `build/firefox/manifest.json`
+
+## 🏗️ Архитектура проекта
+
+### Feature-Sliced Design (FSD)
+Проект использует архитектуру FSD для организации кода:
+
+```
+src/
+├── app/          # Инициализация приложения
+├── pages/        # Страницы (композиция виджетов)
+├── widgets/      # UI блоки высокого уровня
+├── features/     # Пользовательские функции
+├── entities/     # Бизнес-сущности
+└── shared/       # Общие ресурсы
+```
+
+### Правила импортов FSD
+- **Можно импортировать**: только из нижележащих слоев
+- **Нельзя импортировать**: из вышележащих слоев
+- **Горизонтальные импорты**: только через `shared`
+
+Примеры:
+```typescript
+// ✅ Правильно - импорт из shared
+import { generateId } from '#shared/utils/generateId';
+
+// ✅ Правильно - импорт из entities в features
+import { $requestProfiles } from '#entities/request-profile/model';
+
+// ❌ Неправильно - импорт из features в entities
+import { exportProfile } from '#features/export-profile/model';
+```
+
+## 🔄 Управление состоянием (Effector)
+
+### Основные концепции
+
+#### Stores (Хранилища)
+```typescript
+// Создание store
+export const $requestProfiles = createStore<Profile[]>([]);
+
+// Использование в компоненте
+const [profiles] = useUnit([$requestProfiles]);
+```
+
+#### Events (События)
+```typescript
+// Создание события
+export const profileAdded = createEvent();
+
+// Вызов события
+profileAdded(); // Без параметров
+profileUpdated(profile); // С параметрами
+```
+
+#### Effects (Эффекты)
+```typescript
+// Создание эффекта
+const saveProfilesFx = createEffect(saveProfilesToStorage);
+
+// Использование
+sample({
+  clock: profileUpdated,
+  target: saveProfilesFx
+});
+```
+
+### Паттерны Effector
+
+#### Sample для реактивности
+```typescript
+// Обновление store при событии
+sample({
+  clock: profileAdded,
+  source: $requestProfiles,
+  fn: (profiles) => [...profiles, newProfile],
+  target: $requestProfiles
+});
+```
+
+#### Attach для эффектов с параметрами
+```typescript
+const updateProfileFx = attach({
+  source: $requestProfiles,
+  effect: (profiles, profile: Profile) => {
+    // Логика обновления
+    return updatedProfiles;
+  }
+});
+```
+
+## 🎨 UI компоненты
+
+### Структура компонента
+```typescript
+// Компонент с Effector
+export function ProfileComponent() {
+  const [profiles, selectedProfile] = useUnit([
+    $requestProfiles,
+    $selectedProfile
+  ]);
+
+  const handleAddProfile = () => {
+    profileAdded();
+  };
+
+  return (
+    <div>
+      {profiles.map(profile => (
+        <ProfileItem key={profile.id} profile={profile} />
+      ))}
+      <Button onClick={handleAddProfile}>Добавить профиль</Button>
+    </div>
+  );
+}
+```
+
+### Стилизация
+Проект использует Emotion для CSS-in-JS:
+
+```typescript
+import styled from '@emotion/styled';
+
+const StyledButton = styled.button`
+  background-color: ${({ theme }) => theme.colors.primary};
+  padding: 8px 16px;
+  border: none;
+  border-radius: 4px;
+`;
+```
+
+## 🔧 Утилиты и хелперы
+
+### Работа с Chrome API
+```typescript
+// shared/utils/browserAPI.ts
+export const browserAction = {
+  setBadgeText: (text: string) => chrome.action.setBadgeText({ text }),
+  setBadgeBackgroundColor: (color: string) =>
+    chrome.action.setBadgeBackgroundColor({ color })
+};
+```
+
+### Работа с Storage
+```typescript
+// entities/*/utils/save.ts
+export const saveProfilesToStorage = async (profiles: Profile[]) => {
+  await browser.storage.local.set({
+    [BrowserStorageKey.Profiles]: profiles
+  });
+};
+```
+
+### Генерация ID
+```typescript
+// shared/utils/generateId.ts
+export const generateId = (): string => {
+  return Math.random().toString(36).substr(2, 9);
+};
+```
+
+## 🧪 Тестирование
+
+### Unit тесты
+```bash
+# Запуск unit тестов
+pnpm test:unit
+
+# Запуск с покрытием
+pnpm test:unit --coverage
+```
+
+### E2E тесты
+```bash
+# Установка браузеров (первый раз)
+pnpm exec playwright install
+
+# Запуск E2E тестов
+pnpm test:e2e
+
+# Запуск в CI режиме
+pnpm test:e2e:ci
+```
+
+### Структура тестов
+```
+src/shared/utils/__tests__/
+├── formatHeaderValue.spec.ts
+├── generateId.spec.ts
+└── headers.spec.ts
+
+tests/e2e/
+├── basic.spec.ts
+└── fixtures.ts
+```
+
+## 📦 Сборка и деплой
+
+### Команды сборки
+```bash
+# Сборка для Chrome
+pnpm build:chromium
+
+# Сборка для Firefox
+pnpm build:firefox
+
+# Сборка для всех браузеров
+pnpm build
+```
+
+### Структура сборки
+```
+build/
+├── chrome/
+│   ├── manifest.json
+│   ├── popup.html
+│   ├── popup.bundle.js
+│   ├── background.bundle.js
+│   └── styles.css
+└── firefox/
+    └── (аналогичная структура)
+```
+
+## 🔍 Отладка
+
+### Логирование
+```typescript
+import { logger } from '#shared/utils/logger';
+
+// Различные уровни логирования
+logger.debug('Отладочная информация');
+logger.info('Информационное сообщение');
+logger.warn('Предупреждение');
+logger.error('Ошибка');
+```
+
+### Chrome DevTools
+1. Откройте расширение в `chrome://extensions/`
+2. Нажмите "Проверить представления"
+3. Выберите "service worker" для отладки background.ts
+4. Выберите "popup" для отладки UI
+
+### Firefox DevTools
+1. Откройте `about:debugging`
+2. Найдите расширение
+3. Нажмите "Проверить" для отладки
+
+## 🚨 Частые проблемы и решения
+
+### Проблема: Расширение не загружается
+**Решение**: Проверьте manifest.json на ошибки, убедитесь что все файлы собраны
+
+### Проблема: Заголовки не применяются
+**Решение**:
+1. Проверьте права доступа в manifest.json
+2. Убедитесь что Service Worker активен
+3. Проверьте логи в background.ts
+
+### Проблема: Ошибки TypeScript
+**Решение**:
+1. Проверьте алиасы путей в tsconfig.json
+2. Убедитесь что все типы импортированы
+3. Запустите `pnpm lint` для проверки
+
+### Проблема: Стили не применяются
+**Решение**:
+1. Проверьте CSP настройки
+2. Убедитесь что Emotion настроен правильно
+3. Проверьте импорты стилей
+
+## 📚 Полезные ресурсы
+
+### Документация
+- [Chrome Extensions API](https://developer.chrome.com/docs/extensions/)
+- [Effector Documentation](https://effector.dev/)
+- [Feature-Sliced Design](https://feature-sliced.design/)
+- [Playwright Testing](https://playwright.dev/)
+
+### Внутренние ресурсы
+- `PROJECT_MAP.md` - подробная карта проекта
+- `CURSOR_GUIDE.md` - руководство по работе с Cursor
+- `ARCHITECTURE_DIAGRAMS.md` - диаграммы архитектуры
+
+## 🤝 Контрибьюция
+
+### Процесс разработки
+1. Создайте feature branch от `main`
+2. Внесите изменения следуя архитектуре FSD
+3. Добавьте тесты для новой функциональности
+4. Запустите `pnpm lint` и исправьте ошибки
+5. Запустите `pnpm test:unit && pnpm test:e2e`
+6. Создайте Pull Request
+
+### Стандарты кода
+- Используйте TypeScript строго
+- Следуйте архитектуре Feature-Sliced Design
+- Добавляйте комментарии к сложной логике
+- Используйте Effector для управления состоянием
+- Пишите тесты для новой функциональности
+
+### Коммиты
+Используйте conventional commits:
+```
+feat: добавить экспорт профилей
+fix: исправить ошибку сохранения
+docs: обновить документацию
+test: добавить тесты для утилит
+```
+
+## 🔄 CI/CD
+
+### GitHub Actions
+Проект использует GitHub Actions для:
+- Автоматического тестирования
+- Сборки расширений
+- Публикации в Chrome Web Store и Firefox Add-ons
+
+### Релизы
+Релизы создаются автоматически при:
+- Создании тега версии
+- Push в main ветку с определенными коммитами
+
+---
+
+## 💡 Советы по разработке
+
+1. **Начинайте с архитектуры** - понимайте слой FSD перед написанием кода
+2. **Используйте TypeScript строго** - включайте все проверки типов
+3. **Следуйте паттернам Effector** - используйте существующие паттерны
+4. **Тестируйте изменения** - запускайте тесты перед коммитом
+5. **Документируйте сложную логику** - добавляйте комментарии
+6. **Используйте логирование** - добавляйте логи для отладки
+7. **Следуйте принципам FSD** - не нарушайте правила импортов
diff --git a/DOCS_STRUCTURE.md b/DOCS_STRUCTURE.md
new file mode 100644
index 0000000..785fd31
--- /dev/null
+++ b/DOCS_STRUCTURE.md
@@ -0,0 +1,194 @@
+# 📚 Структура документации проекта Cloudhood
+
+## Обзор
+Проект Cloudhood имеет многоязычную документацию, адаптированную для разных аудиторий и целей использования.
+
+## 🌐 Языковые версии
+
+### Основные README файлы
+- **`README.md`** - Международная версия на английском языке
+- **`README.ru.md`** - Русская версия для русскоязычной аудитории
+
+### Переключение языков
+Оба файла содержат ссылки для переключения между языками в верхней части документа.
+
+## 📋 Структура документации
+
+### 1. Основные файлы
+```
+├── README.md                    # 🇺🇸 English (International)
+├── README.ru.md                 # 🇷🇺 Русский (Russian)
+├── .cursorrules                 # 🤖 Cursor AI rules
+└── LICENSE                      # 📄 Apache License 2.0
+```
+
+### 2. Техническая документация
+```
+├── PROJECT_MAP.md               # 🗺️ Project architecture map
+├── CURSOR_GUIDE.md              # 🎯 Cursor IDE guide
+├── ARCHITECTURE_DIAGRAMS.md     # 🏗️ Architecture diagrams
+├── DEVELOPER_GUIDE.md           # 👨‍💻 Developer handbook
+└── CURSOR_IMPROVEMENTS.md       # ✨ Cursor improvements summary
+```
+
+### 3. Настройка и релизы
+```
+├── RELEASE_SETUP.md             # 🚀 Release automation setup
+├── package.json                 # 📦 Project dependencies
+├── tsconfig.json                # ⚙️ TypeScript configuration
+└── vite.config.ts               # 🔧 Build configuration
+```
+
+## 🎯 Целевые аудитории
+
+### Для международных разработчиков
+- **README.md** - Полная информация на английском
+- **PROJECT_MAP.md** - Архитектура и структура проекта
+- **DEVELOPER_GUIDE.md** - Руководство разработчика
+- **ARCHITECTURE_DIAGRAMS.md** - Визуальные схемы
+
+### Для русскоязычной команды
+- **README.ru.md** - Полная информация на русском
+- **CURSOR_GUIDE.md** - Руководство по работе с Cursor
+- **DEVELOPER_GUIDE.md** - Руководство разработчика
+- **CURSOR_IMPROVEMENTS.md** - Итоги улучшений
+
+### Для работы с Cursor AI
+- **.cursorrules** - Правила для AI ассистента
+- **CURSOR_GUIDE.md** - Специфичные запросы и паттерны
+- **PROJECT_MAP.md** - Контекст архитектуры
+
+## 📖 Содержание каждого файла
+
+### README.md (English)
+- **About Cloudhood** - Описание проекта
+- **Key Features** - Основные возможности
+- **Quick Start** - Быстрый старт
+- **Documentation** - Ссылки на документацию
+- **Testing** - Инструкции по тестированию
+- **Development** - Команды разработки
+- **Architecture** - Описание архитектуры
+- **Contributing** - Процесс контрибьюции
+- **Links** - Полезные ссылки
+
+### README.ru.md (Русский)
+- **О Cloudhood** - Описание проекта
+- **Основные возможности** - Ключевые функции
+- **Быстрый старт** - Инструкции по установке
+- **Документация** - Ссылки на документацию
+- **Тестирование** - Инструкции по тестированию
+- **Разработка** - Команды разработки
+- **Архитектура** - Описание архитектуры
+- **Контрибьюция** - Процесс участия в разработке
+- **Ссылки** - Полезные ссылки
+
+### PROJECT_MAP.md
+- **Обзор проекта** - Технологический стек
+- **Архитектура проекта** - Структура папок FSD
+- **Поток данных** - Схемы взаимодействия
+- **Ключевые компоненты** - Описание основных модулей
+- **Утилиты** - Описание вспомогательных функций
+- **Тестирование** - Структура тестов
+- **Сборка и разработка** - Команды и конфигурация
+- **Зависимости** - Описание пакетов
+- **Поиск по проекту** - Паттерны и ключевые файлы
+
+### CURSOR_GUIDE.md
+- **Структура проекта для Cursor** - Навигация по проекту
+- **Поиск и навигация** - Специфичные запросы
+- **Контекстные запросы для AI** - Примеры запросов
+- **Шаблоны компонентов** - Паттерны создания кода
+- **Полезные команды Cursor** - Горячие клавиши
+- **Специфичные запросы** - Для понимания архитектуры
+- **Настройка Cursor** - Рекомендуемые расширения
+- **Быстрые действия** - Частые операции
+- **Отладка и диагностика** - Поиск ошибок
+
+### ARCHITECTURE_DIAGRAMS.md
+- **Общая архитектура** - Mermaid диаграммы
+- **Поток данных Effector** - Схемы состояния
+- **Структура FSD** - Диаграммы слоев
+- **Интеграция с Chrome API** - Sequence диаграммы
+- **Управление состоянием** - State диаграммы
+- **Компонентная архитектура** - UI структура
+- **Статистика проекта** - Метрики и показатели
+
+### DEVELOPER_GUIDE.md
+- **Быстрый старт** - Установка и запуск
+- **Архитектура проекта** - FSD и Effector
+- **Управление состоянием** - Паттерны Effector
+- **UI компоненты** - Структура и стилизация
+- **Утилиты и хелперы** - Вспомогательные функции
+- **Тестирование** - Unit и E2E тесты
+- **Сборка и деплой** - Команды сборки
+- **Отладка** - Логирование и DevTools
+- **Частые проблемы** - Решения типичных ошибок
+- **Полезные ресурсы** - Ссылки на документацию
+
+### CURSOR_IMPROVEMENTS.md
+- **Что было сделано** - Список улучшений
+- **Дополнительные рекомендации** - Дальнейшие улучшения
+- **Как использовать документацию** - Инструкции по использованию
+- **Ожидаемые результаты** - Преимущества улучшений
+- **Заключение** - Итоги работы
+
+## 🔄 Обновление документации
+
+### При добавлении новых функций
+1. Обновить соответствующие разделы в README файлах
+2. Добавить информацию в PROJECT_MAP.md
+3. Обновить примеры в DEVELOPER_GUIDE.md
+4. Добавить диаграммы в ARCHITECTURE_DIAGRAMS.md
+
+### При изменении архитектуры
+1. Обновить PROJECT_MAP.md
+2. Перерисовать диаграммы в ARCHITECTURE_DIAGRAMS.md
+3. Обновить CURSOR_GUIDE.md с новыми запросами
+4. Синхронизировать оба README файла
+
+### При изменении процесса разработки
+1. Обновить DEVELOPER_GUIDE.md
+2. Добавить новые команды в README файлы
+3. Обновить примеры в CURSOR_GUIDE.md
+
+## 📊 Статистика документации
+
+- **Общее количество файлов документации**: 8
+- **Общее количество строк**: ~2,500
+- **Покрытие языков**: English + Русский
+- **Типы документации**: README, Guides, Diagrams, Rules
+- **Форматы**: Markdown, Mermaid диаграммы
+
+## 🎯 Рекомендации по использованию
+
+### Для новых разработчиков
+1. Начните с README на вашем языке
+2. Изучите PROJECT_MAP.md для понимания архитектуры
+3. Прочитайте DEVELOPER_GUIDE.md для настройки окружения
+4. Используйте CURSOR_GUIDE.md для эффективной работы с AI
+
+### Для команды
+1. Следуйте стандартам документирования
+2. Обновляйте документацию при изменениях
+3. Используйте .cursorrules для консистентности с AI
+4. Проверяйте актуальность ссылок между файлами
+
+### Для международной аудитории
+1. Используйте английскую версию README.md
+2. Обращайтесь к DEVELOPER_GUIDE.md для технических деталей
+3. Изучайте ARCHITECTURE_DIAGRAMS.md для понимания структуры
+4. Используйте PROJECT_MAP.md как справочник
+
+---
+
+## 💡 Заключение
+
+Многоязычная документация Cloudhood обеспечивает:
+
+- **Доступность** для международной аудитории
+- **Удобство** для русскоязычной команды
+- **Эффективность** работы с Cursor AI
+- **Полноту** технической информации
+- **Актуальность** и синхронизацию версий
+
+Документация покрывает все аспекты работы с проектом - от быстрого старта до продвинутых техник разработки и работы с AI ассистентами.
diff --git a/PROJECT_MAP.md b/PROJECT_MAP.md
new file mode 100644
index 0000000..c8f8408
--- /dev/null
+++ b/PROJECT_MAP.md
@@ -0,0 +1,204 @@
+# 🗺️ Карта проекта Cloudhood
+
+## Обзор
+Cloudhood - это браузерное расширение для управления HTTP заголовками запросов. Позволяет создавать профили с наборами заголовков и применять их к веб-запросам.
+
+## Технологический стек
+- **Frontend**: React 18 + TypeScript
+- **State Management**: Effector
+- **UI Library**: @snack-uikit (внутренняя библиотека Cloud.ru)
+- **Build Tool**: Vite
+- **Testing**: Vitest + Playwright
+- **Architecture**: Feature-Sliced Design
+
+## Архитектура проекта
+
+### 📁 Структура папок
+
+```
+src/
+├── app/                    # 🚀 Инициализация приложения
+│   ├── App.tsx            # Корневой компонент
+│   └── styles.css         # Глобальные стили
+│
+├── pages/                  # 📄 Страницы приложения
+│   └── main/              # Главная страница
+│       ├── Main.tsx       # Основной интерфейс
+│       └── components/    # Компоненты страницы
+│
+├── widgets/               # 🧩 Переиспользуемые UI блоки
+│   ├── header/            # Шапка с профилями и действиями
+│   │   ├── Header.tsx    # Компонент шапки
+│   │   └── components/    # Подкомпоненты шапки
+│   ├── sidebar/           # Боковая панель с профилями
+│   ├── request-headers/   # Список заголовков запросов
+│   └── modals/            # Модальные окна
+│
+├── features/              # ⚡ Бизнес-функции
+│   ├── export-profile/    # Экспорт профилей в JSON
+│   ├── import-profile/    # Импорт профилей из файлов
+│   ├── copy-active-request-headers/ # Копирование активных заголовков
+│   └── selected-profile-request-headers/ # CRUD операции с заголовками
+│
+├── entities/              # 🏗️ Бизнес-сущности
+│   ├── request-profile/   # Профили заголовков (основная сущность)
+│   ├── notification/      # Система уведомлений
+│   ├── modal/             # Управление модальными окнами
+│   ├── is-paused/         # Состояние паузы
+│   └── themeMode/         # Темная/светлая тема
+│
+├── shared/                # 🔧 Общие ресурсы
+│   ├── components/        # Переиспользуемые компоненты
+│   ├── utils/             # Утилиты и хелперы
+│   ├── assets/            # Статические ресурсы (иконки, шрифты)
+│   ├── constants.ts       # Константы приложения
+│   └── model.ts           # Общие модели Effector
+│
+├── background.ts          # 🔄 Service Worker расширения
+├── index.tsx             # Точка входа React приложения
+└── index.html            # HTML шаблон
+```
+
+### 🔄 Поток данных
+
+1. **Инициализация**: `background.ts` → `shared/model.ts` → `app/App.tsx`
+2. **Управление профилями**: `entities/request-profile/` → `widgets/sidebar/`
+3. **Управление заголовками**: `features/selected-profile-request-headers/` → `widgets/request-headers/`
+4. **Сохранение данных**: `shared/utils/` → Chrome Storage API
+
+### 🎯 Ключевые компоненты
+
+#### Request Profile (Профиль запросов)
+- **Расположение**: `src/entities/request-profile/`
+- **Назначение**: Основная сущность для хранения наборов заголовков
+- **Структура**: `{ id, name, headers: [{ key, value }] }`
+
+#### Service Worker
+- **Файл**: `src/background.ts`
+- **Назначение**: Обработка событий расширения, управление заголовками
+- **API**: Chrome Declarative Net Request
+
+#### UI Компоненты
+- **Header**: Управление профилями, пауза/воспроизведение
+- **Sidebar**: Список профилей, создание/удаление
+- **Request Headers**: Редактирование заголовков профиля
+
+### 🔧 Утилиты
+
+#### Browser API (`shared/utils/browserAPI.ts`)
+- Обертка над Chrome Extension API
+- Поддержка Firefox через webextension-polyfill
+
+#### Headers Management (`shared/utils/setBrowserHeaders.ts`)
+- Применение заголовков через Declarative Net Request
+- Обработка правил динамических запросов
+
+#### Storage (`entities/*/utils/load.ts`, `entities/*/utils/save.ts`)
+- Загрузка/сохранение данных в Chrome Storage
+- Типизированные интерфейсы для каждой сущности
+
+### 🧪 Тестирование
+
+#### Unit Tests
+- **Расположение**: `src/shared/utils/__tests__/`
+- **Фреймворк**: Vitest
+- **Покрытие**: Утилиты форматирования, генерации ID
+
+#### E2E Tests
+- **Расположение**: `tests/e2e/`
+- **Фреймворк**: Playwright
+- **Сценарии**: Основные пользовательские сценарии
+
+### 🚀 Сборка и разработка
+
+#### Команды разработки
+```bash
+pnpm dev:chrome    # Разработка для Chrome с hot reload
+pnpm dev:firefox   # Разработка для Firefox с hot reload
+```
+
+#### Сборка
+```bash
+pnpm build:chromium  # Сборка для Chrome
+pnpm build:firefox   # Сборка для Firefox
+pnpm build          # Сборка для всех браузеров
+```
+
+#### Конфигурация
+- **Vite**: `vite.config.ts` - настройка сборки для расширений
+- **TypeScript**: `tsconfig.json` - алиасы путей, настройки компиляции
+- **ESLint**: `eslint.config.mjs` - правила линтинга
+
+### 📦 Зависимости
+
+#### Основные
+- `react` + `react-dom` - UI фреймворк
+- `effector` + `effector-react` - управление состоянием
+- `@snack-uikit/*` - UI компоненты Cloud.ru
+
+#### Разработка
+- `vite` - сборщик
+- `@crxjs/vite-plugin` - поддержка расширений
+- `@playwright/test` - E2E тестирование
+- `vitest` - unit тестирование
+
+### 🔍 Поиск по проекту
+
+#### Часто используемые паттерны
+- **Effector stores**: `$` префикс (например, `$selectedProfileIndex`)
+- **Effector events**: `createEvent()` для действий
+- **Effector effects**: `createEffect()` для асинхронных операций
+- **React hooks**: `useUnit()` для подключения к Effector
+
+#### Ключевые файлы для понимания
+1. `src/background.ts` - логика расширения
+2. `src/entities/request-profile/model/` - основная бизнес-логика
+3. `src/widgets/header/Header.tsx` - главный UI компонент
+4. `src/shared/utils/setBrowserHeaders.ts` - применение заголовков
+
+### 🎨 UI/UX
+
+#### Дизайн система
+- **Цвета**: `src/shared/assets/colors/` - палитра профилей
+- **Иконки**: `src/shared/assets/svg/` - SVG иконки
+- **Шрифты**: `src/assets/fonts/` - корпоративные шрифты SBSans
+
+#### Компоненты
+- **Snack UI Kit**: Внутренняя библиотека компонентов Cloud.ru
+- **Emotion**: CSS-in-JS для стилизации
+- **Drag & Drop**: `@dnd-kit` для перетаскивания заголовков
+
+### 🔐 Безопасность
+
+#### Content Security Policy
+- **CSP**: Настроен в `src/shared/utils/csp.ts`
+- **Nonce**: Динамическая генерация для стилей
+
+#### Permissions
+- **Manifest**: `manifest.chromium.json` / `manifest.firefox.json`
+- **Declarative Net Request**: Управление заголовками запросов
+- **Storage**: Локальное хранение профилей
+
+---
+
+## 🚀 Быстрый старт для разработчиков
+
+1. **Клонирование**: `git clone <repo>`
+2. **Установка**: `pnpm install`
+3. **Разработка**: `pnpm dev:chrome`
+4. **Тестирование**: `pnpm test:unit` / `pnpm test:e2e`
+5. **Сборка**: `pnpm build`
+
+## 📝 Контрибьюция
+
+1. Создайте feature branch
+2. Внесите изменения
+3. Запустите тесты: `pnpm test:unit && pnpm test:e2e`
+4. Создайте Pull Request
+
+## 🔗 Полезные ссылки
+
+- [Chrome Extension API](https://developer.chrome.com/docs/extensions/)
+- [Effector Documentation](https://effector.dev/)
+- [Feature-Sliced Design](https://feature-sliced.design/)
+- [Playwright Testing](https://playwright.dev/)
diff --git a/README.md b/README.md
index 4790cec..f07d730 100755
--- a/README.md
+++ b/README.md
@@ -5,84 +5,157 @@
 <a href="https://chrome.google.com/webstore/detail/cloudhood/hohljodjndmmaiedadcdmnelgdfnbfgp"><img alt="Chrome Web Store Version" src="https://img.shields.io/chrome-web-store/v/hohljodjndmmaiedadcdmnelgdfnbfgp?label=Chrome%20Web%20Store%20Version"></a>
 <a href="https://github.com/cloud-ru-tech/cloudhood/releases"><img alt="GitHub Release Date" src="https://img.shields.io/github/release-date/cloud-ru-tech/cloudhood?label=Release%20Date" /></a>
 
-This extension allows users to control request headers that will be embedded in all requests in Chrome Browser, where each override contains the following properties:
+## 🌐 Language / Язык
 
-- Header: Header key.
-- Header Value: The value associated with the header key.
+- **[English](README.md)** (International version)
+- **[Русский](README.ru.md)** (Russian version)
 
-Header overrides are managed in a Chrome extension popup (a simple react app), stored in Chrome local storage, and applied to upstream page requests using the updateDynamicRules function of chrome's declarativeNetRequest dynamic request rules.
+---
 
-## Testing
+## About Cloudhood
 
-You can get a test build for each pull-request in its comments. [Example](https://github.com/cloud-ru-tech/cloudhood/pull/1#issuecomment-1713810507).
+Cloudhood is a powerful browser extension that allows users to control HTTP request headers that will be embedded in all web requests. Built with modern web technologies and following Feature-Sliced Design architecture principles.
 
-### E2E Testing
+### Key Features
 
-For E2E tests, always import the test fixtures:
+- **Header Management**: Create, edit, and manage custom HTTP headers
+- **Profile System**: Organize headers into reusable profiles
+- **Cross-Browser Support**: Works on Chrome and Firefox
+- **Import/Export**: Share profiles between devices and team members
+- **Real-time Application**: Headers are applied instantly to web requests
+- **Modern UI**: Clean, intuitive interface built with React and TypeScript
 
-```typescript
-import { expect, test } from './fixtures';
+### How It Works
+
+Header overrides are managed through a Chrome extension popup (React application), stored in browser local storage, and applied to upstream page requests using Chrome's Declarative Net Request API.
+
+## 📚 Documentation
+
+- **[Project Map](PROJECT_MAP.md)** - Detailed architecture and project structure overview
+- **[Cursor Guide](CURSOR_GUIDE.md)** - How to work effectively with the project in Cursor IDE
+- **[Architecture Diagrams](ARCHITECTURE_DIAGRAMS.md)** - Visual schemas of architecture and data flows
+- **[Developer Guide](DEVELOPER_GUIDE.md)** - Complete developer handbook
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- Node.js >= 20.0.0
+- pnpm >= 10.10.0
+- Chrome or Firefox browser
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/cloud-ru-tech/cloudhood.git
+cd cloudhood
+
+# Install dependencies
+pnpm install
+
+# Start development server for Chrome
+pnpm dev:chrome
+
+# Start development server for Firefox
+pnpm dev:firefox
 ```
 
-Before running E2E tests for the first time, install the required browsers:
+### Loading the Extension
+
+#### Chrome
+1. Open `chrome://extensions/`
+2. Enable "Developer mode"
+3. Click "Load unpacked extension"
+4. Select the `build/chrome` directory
+
+#### Firefox
+1. Open `about:debugging`
+2. Click "This Firefox"
+3. Click "Load Temporary Add-on"
+4. Select `build/firefox/manifest.json`
+
+## 🧪 Testing
+
+### Unit Tests
 
 ```bash
-pnpm exec playwright install
+# Run unit tests
+pnpm test:unit
+
+# Run with coverage
+pnpm test:unit --coverage
 ```
 
-Run E2E tests with:
+### E2E Tests
 
 ```bash
+# Install browsers (first time only)
+pnpm exec playwright install
+
+# Run E2E tests
 pnpm test:e2e
+
+# Run in CI mode
+pnpm test:e2e:ci
 ```
 
-## Local Development
+For E2E tests, always import the test fixtures:
 
-### Development Server with Hot Reload
+```typescript
+import { expect, test } from './fixtures';
+```
 
-For convenient development with automatic reload, use the following commands:
+## 🛠️ Development
 
-#### Chrome Development (with hot reload)
+### Development Commands
 
 ```bash
+# Chrome development with hot reload
 pnpm dev:chrome
-```
 
-#### Firefox Development (with hot reload)
-
-```bash
+# Firefox development with hot reload
 pnpm dev:firefox
-```
 
-These commands will start a dev server that will automatically update files in the `build` directory when source code changes.
+# Build for Chrome
+pnpm build:chromium
+
+# Build for Firefox
+pnpm build:firefox
 
-### Start Local Server (legacy method)
+# Build for all browsers
+pnpm build
 
-1. Run `pnpm install` to install the dependencies.
-1. Run `pnpm start`
-1. Download extension in Chrome:
-   - Open `chrome://extensions/` in the address bar
-   - Turn on `Developer mode`
-   - Click `Load unpacked extension`
-   - Select `build` directory.
+# Lint code
+pnpm lint
+```
 
-## Development for different browsers
+### Architecture
 
-### Chrome Development
+The project follows **Feature-Sliced Design** architecture:
 
-```bash
-pnpm dev:chrome    # with hot reload (recommended)
+```
+src/
+├── app/          # Application initialization
+├── pages/        # Pages (widget composition)
+├── widgets/      # High-level UI blocks
+├── features/     # User-facing features
+├── entities/     # Business entities
+└── shared/       # Shared resources
 ```
 
-### Firefox Development
+### Technology Stack
 
-```bash
-pnpm dev:firefox    # with hot reload (recommended)
-```
+- **Frontend**: React 18 + TypeScript
+- **State Management**: Effector
+- **UI Library**: @snack-uikit (Cloud.ru internal library)
+- **Build Tool**: Vite
+- **Testing**: Vitest + Playwright
+- **Architecture**: Feature-Sliced Design
 
-## Building Extensions
+## 📦 Building Extensions
 
-### Build Chrome Extension
+### Chrome Extension
 
 ```bash
 pnpm build:chromium
@@ -90,7 +163,7 @@ pnpm build:chromium
 
 The extension will be built in the `build/chrome` directory.
 
-### Build Firefox Extension
+### Firefox Extension
 
 ```bash
 pnpm build:firefox
@@ -98,7 +171,7 @@ pnpm build:firefox
 
 The extension will be built in the `build/firefox` directory.
 
-### Build Firefox Sources Archive
+### Firefox Sources Archive
 
 ```bash
 npm run build:firefox-sources
@@ -106,13 +179,7 @@ npm run build:firefox-sources
 
 Creates a ZIP archive with source code required for Firefox Add-ons submission. Mozilla requires source code submission for extensions that use build tools or minification.
 
-### Build Both Extensions
-
-```bash
-pnpm build
-```
-
-## Releasing
+## 🚀 Releasing
 
 We use GitHub Actions to automate the release process. The workflow:
 
@@ -125,18 +192,50 @@ We use GitHub Actions to automate the release process. The workflow:
 
 See [RELEASE_SETUP.md](RELEASE_SETUP.md) for details on configuring the release automation.
 
-## Packing
+## 🤝 Contributing
+
+### Development Process
+
+1. Create a feature branch from `main`
+2. Make changes following FSD architecture
+3. Add tests for new functionality
+4. Run `pnpm lint` and fix any issues
+5. Run `pnpm test:unit && pnpm test:e2e`
+6. Create a Pull Request
 
-After developing your extension, run the command
+### Code Standards
+
+- Use TypeScript strictly
+- Follow Feature-Sliced Design architecture
+- Add comments for complex logic
+- Use Effector for state management
+- Write tests for new functionality
+
+### Commits
+
+Use conventional commits:
 
 ```
-pnpm run build
+feat: add profile export functionality
+fix: resolve header saving issue
+docs: update documentation
+test: add tests for utilities
 ```
 
-## Releases
+## 🔗 Links
+
+- **Chrome Web Store**: [Install Cloudhood](https://chrome.google.com/webstore/detail/cloudhood/hohljodjndmmaiedadcdmnelgdfnbfgp)
+- **Firefox Add-ons**: [Install Cloudhood](https://addons.mozilla.org/en-US/firefox/addon/cloudhood/)
+- **GitHub Releases**: [Latest Releases](https://github.com/cloud-ru-tech/cloudhood/releases)
+
+## 📄 License
+
+[Apache License 2.0](LICENSE)
+
+---
 
-The repository is configured with actions for automatic releases to Github.
+## 🏢 About Cloud.ru
 
-# License
+Cloudhood is developed by [Cloud.ru](https://cloud.ru/) - a leading Russian cloud provider offering comprehensive cloud solutions and services.
 
-[Apache License 2.0](LICENSE).
+**Made with ❤️ by the Cloud.ru team**
\ No newline at end of file
diff --git a/README.ru.md b/README.ru.md
new file mode 100644
index 0000000..30726d2
--- /dev/null
+++ b/README.ru.md
@@ -0,0 +1,241 @@
+![Cloudhood](https://github.com/cloud-ru-tech/cloudhood/assets/24465747/0a026d8b-be14-4f1f-9be3-d4e6056aea20)
+
+<a href="https://chrome.google.com/webstore/detail/cloudhood/hohljodjndmmaiedadcdmnelgdfnbfgp"><img alt="Chrome Web Store Rating" src="https://img.shields.io/chrome-web-store/rating/hohljodjndmmaiedadcdmnelgdfnbfgp?label=Chrome%20Web%20Store%20Rating"></a>
+<a href="https://chrome.google.com/webstore/detail/cloudhood/hohljodjndmmaiedadcdmnelgdfnbfgp"><img alt="Chrome Web Store Users" src="https://img.shields.io/chrome-web-store/users/hohljodjndmmaiedadcdmnelgdfnbfgp?label=Chrome%20Web%20Store%20Users&color=%2325c2a0"></a>
+<a href="https://chrome.google.com/webstore/detail/cloudhood/hohljodjndmmaiedadcdmnelgdfnbfgp"><img alt="Chrome Web Store Version" src="https://img.shields.io/chrome-web-store/v/hohljodjndmmaiedadcdmnelgdfnbfgp?label=Chrome%20Web%20Store%20Version"></a>
+<a href="https://github.com/cloud-ru-tech/cloudhood/releases"><img alt="GitHub Release Date" src="https://img.shields.io/github/release-date/cloud-ru-tech/cloudhood?label=Release%20Date" /></a>
+
+## 🌐 Язык / Language
+
+- **[Русский](README.ru.md)** (Русская версия)
+- **[English](README.md)** (International version)
+
+---
+
+## О Cloudhood
+
+Cloudhood — это мощное браузерное расширение, которое позволяет пользователям управлять HTTP заголовками запросов, которые будут встроены во все веб-запросы. Построено на современных веб-технологиях с использованием архитектуры Feature-Sliced Design.
+
+### Основные возможности
+
+- **Управление заголовками**: Создание, редактирование и управление пользовательскими HTTP заголовками
+- **Система профилей**: Организация заголовков в переиспользуемые профили
+- **Кроссплатформенность**: Работает в Chrome и Firefox
+- **Импорт/Экспорт**: Обмен профилями между устройствами и участниками команды
+- **Применение в реальном времени**: Заголовки применяются мгновенно к веб-запросам
+- **Современный UI**: Чистый, интуитивный интерфейс на React и TypeScript
+
+### Как это работает
+
+Переопределения заголовков управляются через popup расширения Chrome (React приложение), сохраняются в локальном хранилище браузера и применяются к исходящим запросам страниц с помощью Chrome Declarative Net Request API.
+
+## 📚 Документация
+
+- **[Карта проекта](PROJECT_MAP.md)** - Подробная карта архитектуры и структуры проекта
+- **[Руководство по Cursor](CURSOR_GUIDE.md)** - Как эффективно работать с проектом в Cursor IDE
+- **[Диаграммы архитектуры](ARCHITECTURE_DIAGRAMS.md)** - Визуальные схемы архитектуры и потоков данных
+- **[Руководство разработчика](DEVELOPER_GUIDE.md)** - Полное руководство для разработчиков
+
+## 🚀 Быстрый старт
+
+### Предварительные требования
+
+- Node.js >= 20.0.0
+- pnpm >= 10.10.0
+- Браузер Chrome или Firefox
+
+### Установка
+
+```bash
+# Клонирование репозитория
+git clone https://github.com/cloud-ru-tech/cloudhood.git
+cd cloudhood
+
+# Установка зависимостей
+pnpm install
+
+# Запуск сервера разработки для Chrome
+pnpm dev:chrome
+
+# Запуск сервера разработки для Firefox
+pnpm dev:firefox
+```
+
+### Загрузка расширения
+
+#### Chrome
+1. Откройте `chrome://extensions/`
+2. Включите "Режим разработчика"
+3. Нажмите "Загрузить распакованное расширение"
+4. Выберите папку `build/chrome`
+
+#### Firefox
+1. Откройте `about:debugging`
+2. Нажмите "Этот Firefox"
+3. Нажмите "Загрузить временное дополнение"
+4. Выберите файл `build/firefox/manifest.json`
+
+## 🧪 Тестирование
+
+### Unit тесты
+
+```bash
+# Запуск unit тестов
+pnpm test:unit
+
+# Запуск с покрытием
+pnpm test:unit --coverage
+```
+
+### E2E тесты
+
+```bash
+# Установка браузеров (только первый раз)
+pnpm exec playwright install
+
+# Запуск E2E тестов
+pnpm test:e2e
+
+# Запуск в CI режиме
+pnpm test:e2e:ci
+```
+
+Для E2E тестов всегда импортируйте фикстуры:
+
+```typescript
+import { expect, test } from './fixtures';
+```
+
+## 🛠️ Разработка
+
+### Команды разработки
+
+```bash
+# Разработка для Chrome с hot reload
+pnpm dev:chrome
+
+# Разработка для Firefox с hot reload
+pnpm dev:firefox
+
+# Сборка для Chrome
+pnpm build:chromium
+
+# Сборка для Firefox
+pnpm build:firefox
+
+# Сборка для всех браузеров
+pnpm build
+
+# Линтинг кода
+pnpm lint
+```
+
+### Архитектура
+
+Проект следует архитектуре **Feature-Sliced Design**:
+
+```
+src/
+├── app/          # Инициализация приложения
+├── pages/        # Страницы (композиция виджетов)
+├── widgets/      # UI блоки высокого уровня
+├── features/     # Пользовательские функции
+├── entities/     # Бизнес-сущности
+└── shared/       # Общие ресурсы
+```
+
+### Технологический стек
+
+- **Frontend**: React 18 + TypeScript
+- **Управление состоянием**: Effector
+- **UI библиотека**: @snack-uikit (внутренняя библиотека Cloud.ru)
+- **Сборщик**: Vite
+- **Тестирование**: Vitest + Playwright
+- **Архитектура**: Feature-Sliced Design
+
+## 📦 Сборка расширений
+
+### Chrome Extension
+
+```bash
+pnpm build:chromium
+```
+
+Расширение будет собрано в директории `build/chrome`.
+
+### Firefox Extension
+
+```bash
+pnpm build:firefox
+```
+
+Расширение будет собрано в директории `build/firefox`.
+
+### Архив исходного кода Firefox
+
+```bash
+npm run build:firefox-sources
+```
+
+Создает ZIP архив с исходным кодом, необходимым для подачи в Firefox Add-ons. Mozilla требует предоставления исходного кода для расширений, использующих инструменты сборки или минификацию.
+
+## 🚀 Релизы
+
+Мы используем GitHub Actions для автоматизации процесса релизов. Workflow:
+
+1. Увеличивает версию на основе сообщений коммитов
+2. Собирает расширения для Chrome и Firefox
+3. Создает ZIP архивы для обеих платформ
+4. Создает архив исходного кода для подачи в Firefox Add-ons
+5. Публикует в Chrome Web Store и Firefox Add-ons (с исходным кодом)
+6. Создает GitHub Release с пакетами расширений для обеих платформ
+
+См. [RELEASE_SETUP.md](RELEASE_SETUP.md) для подробностей настройки автоматизации релизов.
+
+## 🤝 Контрибьюция
+
+### Процесс разработки
+
+1. Создайте feature branch от `main`
+2. Внесите изменения следуя архитектуре FSD
+3. Добавьте тесты для новой функциональности
+4. Запустите `pnpm lint` и исправьте ошибки
+5. Запустите `pnpm test:unit && pnpm test:e2e`
+6. Создайте Pull Request
+
+### Стандарты кода
+
+- Используйте TypeScript строго
+- Следуйте архитектуре Feature-Sliced Design
+- Добавляйте комментарии к сложной логике
+- Используйте Effector для управления состоянием
+- Пишите тесты для новой функциональности
+
+### Коммиты
+
+Используйте conventional commits:
+
+```
+feat: добавить функциональность экспорта профилей
+fix: исправить ошибку сохранения заголовков
+docs: обновить документацию
+test: добавить тесты для утилит
+```
+
+## 🔗 Ссылки
+
+- **Chrome Web Store**: [Установить Cloudhood](https://chrome.google.com/webstore/detail/cloudhood/hohljodjndmmaiedadcdmnelgdfnbfgp)
+- **Firefox Add-ons**: [Установить Cloudhood](https://addons.mozilla.org/en-US/firefox/addon/cloudhood/)
+- **GitHub Releases**: [Последние релизы](https://github.com/cloud-ru-tech/cloudhood/releases)
+
+## 📄 Лицензия
+
+[Apache License 2.0](LICENSE)
+
+---
+
+## 🏢 О Cloud.ru
+
+Cloudhood разработан командой [Cloud.ru](https://cloud.ru/) — ведущего российского облачного провайдера, предлагающего комплексные облачные решения и сервисы.
+
+**Сделано с ❤️ командой Cloud.ru**
diff --git a/src/background.ts b/src/background.ts
index 39c65af..f248914 100644
--- a/src/background.ts
+++ b/src/background.ts
@@ -1,3 +1,15 @@
+/**
+ * Service Worker для браузерного расширения Cloudhood
+ *
+ * Этот файл содержит логику Service Worker, которая:
+ * - Обрабатывает события расширения (установка, запуск, обновление)
+ * - Управляет HTTP заголовками через Declarative Net Request API
+ * - Синхронизирует состояние с Chrome Storage
+ * - Обрабатывает сообщения от popup UI
+ *
+ * Service Worker работает в фоновом режиме и не имеет прямого доступа к DOM
+ */
+
 import browser from 'webextension-polyfill';
 
 import { BrowserStorageKey, ServiceWorkerEvent } from './shared/constants';
diff --git a/src/entities/request-profile/model/request-profiles.ts b/src/entities/request-profile/model/request-profiles.ts
index b251433..8d60b47 100644
--- a/src/entities/request-profile/model/request-profiles.ts
+++ b/src/entities/request-profile/model/request-profiles.ts
@@ -1,3 +1,15 @@
+/**
+ * Модель управления профилями запросов (Request Profiles)
+ *
+ * Этот файл содержит основную бизнес-логику для работы с профилями заголовков:
+ * - CRUD операции с профилями
+ * - Автоматическое сохранение в Chrome Storage
+ * - Синхронизация с выбранным профилем
+ *
+ * Архитектура: Entity слой Feature-Sliced Design
+ * Использует Effector для управления состоянием
+ */
+
 import { attach, createEffect, createEvent, createStore, sample } from 'effector';
 
 import { initApp } from '#shared/model';
@@ -11,15 +23,36 @@ import {
   selectedRequestProfileIdChanged,
 } from './selected-request-profile';
 
+// === Effector Events (События) ===
+// События для управления профилями - вызываются из UI компонентов
+
+/** Событие добавления нового профиля */
 export const profileAdded = createEvent();
+
+/** Событие добавления нескольких профилей (при импорте) */
 export const profileMultiAdded = createEvent<Profile[]>();
+
+/** Событие удаления профиля по ID */
 export const profileRemoved = createEvent<Profile['id']>();
+
+/** Событие удаления нескольких профилей */
 export const profileMultiRemoved = createEvent<Profile['id'][]>();
+
+/** Событие обновления профиля */
 export const profileUpdated = createEvent<Profile>();
 
+// === Effector Effects (Эффекты) ===
+// Асинхронные операции для работы с Chrome Storage API
+
+/** Эффект сохранения профилей в Chrome Storage */
 const profilesSavedToBrowserFx = createEffect(saveProfilesToBrowserApi);
+
+/** Эффект загрузки профилей из Chrome Storage */
 const profilesLoadedFromStorageFx = createEffect(loadProfilesFromStorageApi);
 
+// === Effector Store (Хранилище состояния) ===
+
+/** Основное хранилище всех профилей запросов */
 export const $requestProfiles = createStore<Profile[]>([]);
 
 sample({