Исправления в ветке auth-feature

docs/USAGE_GUIDE.md

@@ -0,0 +1,642 @@
+# Руководство по использованию (USAGE_GUIDE)
+
+## Что это
+
+Linux Command GPT (`lcg`) преобразует описание на естественном языке в готовую команду для Linux или Windows. Инструмент автоматически определяет операционную систему и использует соответствующие промпты. Поддерживает сменные провайдеры LLM (Ollama или Proxy), управление системными промптами, историю запросов, сохранение результатов, HTTP сервер для просмотра результатов, аутентификацию, CSRF защиту, интерактивные действия над сгенерированной командой и деплой в Kubernetes.
+
+## Требования
+
+- Установленный Go (для сборки из исходников) или готовый бинарник.
+- Для функции «скопировать в буфер обмена»: установите `xclip` или `xsel`.
+
+```bash
+# Debian/Ubuntu
+sudo apt-get install xclip
+# или
+sudo apt-get install xsel
+```
+
+## Установка
+
+Сборка из исходников:
+
+```bash
+
+git clone --depth 1 https://github.com/Direct-Dev-Ru/go-lcg.git ~/.linux-command-gpt
+cd ~/.linux-command-gpt
+go build -o lcg
+
+# Добавьте бинарник в PATH
+ln -s ~/.linux-command-gpt/lcg ~/.local/bin
+```
+
+Или скачайте готовый бинарник из раздела релизов.
+
+## Быстрый старт
+
+Простой запрос:
+
+```bash
+lcg "хочу извлечь файл linux-command-gpt.tar.gz"
+```
+
+Смешанный ввод: часть из файла, часть — текстом:
+
+```bash
+lcg --file /path/to/context.txt "хочу вывести список директорий с помощью ls"
+```
+
+После генерации вы увидите:
+
+```text
+🤖 Запрос: <ваше описание>
+✅ Выполнено за X.XX сек
+
+ВНИМАНИЕ: ОТВЕТ СФОРМИРОВАН ИИ. ТРЕБУЕТСЯ ПРОВЕРКА И КРИТИЧЕСКИЙ АНАЛИЗ. ВОЗМОЖНЫ ОШИБКИ И ГАЛЛЮЦИНАЦИИ.
+
+📋 Команда:
+   <сгенерированная команда>
+
+Действия: (c)копировать, (s)сохранить, (r)перегенерировать, (e)выполнить, (v|vv|vvv)подробно, (n)ничего:
+```
+
+### Что нового в 3.0.0
+
+- **Аутентификация**: Добавлена система аутентификации с JWT токенами и HTTP-only cookies
+- **CSRF защита**: Полная защита от CSRF атак с токенами и middleware
+- **Безопасность**: Улучшенная безопасность с проверкой токенов и сессий
+- **Kubernetes деплой**: Полный набор манифестов для деплоя в Kubernetes с Traefik
+- **Flux CD**: GitOps конфигурация для автоматического деплоя
+- **Reverse Proxy**: Поддержка работы за reverse proxy с настройкой cookies
+- **Веб-интерфейс**: Улучшенный веб-интерфейс с современным дизайном
+- **Мониторинг**: Prometheus метрики и ServiceMonitor
+- **Масштабирование**: HPA для автоматического масштабирования
+- **Тестирование**: Инструменты для тестирования CSRF защиты
+
+## Переменные окружения
+
+Можно настроить поведение без изменения командной строки.
+
+| Переменная | Значение по умолчанию | Назначение |
+| --- | --- | --- |
+| `LCG_HOST` | `http://192.168.87.108:11434/` | Базовый URL API провайдера (для Ollama поставьте, например, `http://localhost:11434/`). |
+| `LCG_PROXY_URL` | `/api/v1/protected/sberchat/chat` | Относительный путь эндпоинта для Proxy провайдера. |
+| `LCG_COMPLETIONS_PATH` | `api/chat` | Относительный путь эндпоинта для Ollama. |
+| `LCG_MODEL` | `hf.co/yandex/YandexGPT-5-Lite-8B-instruct-GGUF:Q4_K_M` | Имя модели у выбранного провайдера. |
+| `LCG_PROMPT` | См. значение в коде | Содержимое системного промпта по умолчанию. |
+| `LCG_API_KEY_FILE` | `.openai_api_key` | Файл с API‑ключом (для Ollama/Proxy не требуется). |
+| `LCG_RESULT_FOLDER` | `~/.config/lcg/gpt_results` | Папка для сохранения результатов. |
+| `LCG_PROVIDER` | `ollama` | Тип провайдера: `ollama` или `proxy`. |
+| `LCG_JWT_TOKEN` | пусто | JWT токен для `proxy` провайдера (альтернатива — файл `~/.proxy_jwt_token`). |
+| `LCG_PROMPT_ID` | `1` | ID системного промпта по умолчанию. |
+| `LCG_BROWSER_PATH` | пусто | Путь к браузеру для автооткрытия (`--browser`). |
+| `LCG_TIMEOUT` | `300` | Таймаут запроса в секундах. |
+| `LCG_RESULT_HISTORY` | `$(LCG_RESULT_FOLDER)/lcg_history.json` | Путь к JSON‑истории запросов. |
+| `LCG_PROMPT_FOLDER` | `~/.config/lcg/gpt_sys_prompts` | Папка для хранения системных промптов. |
+| `LCG_NO_HISTORY` | пусто | Если `1`/`true` — полностью отключает запись/обновление истории. |
+| `LCG_ALLOW_EXECUTION` | пусто | Если `1`/`true` — включает возможность выполнения команд через опцию `(e)` в меню действий. |
+| `LCG_SERVER_PORT` | `8080` | Порт для HTTP сервера просмотра результатов. |
+| `LCG_SERVER_HOST` | `localhost` | Хост для HTTP сервера просмотра результатов. |
+| `LCG_SERVER_REQUIRE_AUTH` | `false` | Требовать аутентификацию для доступа к веб-интерфейсу. |
+| `LCG_SERVER_PASSWORD` | `admin#123456` | Пароль для аутентификации. |
+| `LCG_COOKIE_SECURE` | `false` | Использовать Secure флаг для cookies (для HTTPS). |
+| `LCG_DOMAIN` | пусто | Домен для cookies (для reverse proxy). |
+| `LCG_COOKIE_PATH` | `/` | Путь для cookies (для reverse proxy). |
+| `LCG_COOKIE_TTL_HOURS` | `168` | Время жизни cookies в часах (по умолчанию 7 дней). |
+| `LCG_CSRF_SECRET` | пусто | Секрет для CSRF токенов (генерируется автоматически). |
+
+Примеры настройки:
+
+```bash
+# Ollama
+export LCG_PROVIDER=ollama
+export LCG_HOST=http://localhost:11434/
+export LCG_MODEL=codegeex4
+
+# Proxy
+export LCG_PROVIDER=proxy
+export LCG_HOST=http://localhost:8080
+export LCG_MODEL=GigaChat-2
+export LCG_JWT_TOKEN=your_jwt_token_here
+
+# Аутентификация и безопасность
+export LCG_SERVER_REQUIRE_AUTH=true
+export LCG_SERVER_PASSWORD=my_secure_password
+export LCG_COOKIE_SECURE=false
+export LCG_DOMAIN=.example.com
+export LCG_COOKIE_PATH=/lcg
+export LCG_COOKIE_TTL_HOURS=72  # 3 дня
+```
+
+## Базовый синтаксис
+
+```bash
+lcg [глобальные опции] <описание команды>
+```
+
+Глобальные опции:
+
+- `--file, -f string` — прочитать часть запроса из файла и добавить к описанию.
+- `--sys, -s string` — системный промпт (содержимое или ID как строка). Если не задан, используется `--prompt-id` или `LCG_PROMPT`.
+- `--prompt-id, --pid int` — ID системного промпта (1–5 для стандартных, либо ваш кастомный ID).
+- `--timeout, -t int` — таймаут запроса в секундах (по умолчанию 120; через `LCG_TIMEOUT` — 300).
+- `--no-history, --nh` — отключить запись/обновление истории для текущего запуска.
+- `--debug, -d` — показать отладочную информацию (параметры запроса и промпты).
+- `--version, -v` — вывести версию.
+- `--help, -h` — помощь.
+
+## Подкоманды
+
+- `lcg update-key` (`-u`): обновить API‑ключ. Для `ollama` и `proxy` не требуется — команда сообщит, что ключ не нужен.
+- `lcg delete-key` (`-d`): удалить API‑ключ (не требуется для `ollama`/`proxy`).
+- `lcg update-jwt` (`-j`): обновить JWT для `proxy`. Токен будет сохранён в `~/.proxy_jwt_token` (права `0600`).
+- `lcg delete-jwt` (`-dj`): удалить JWT файл для `proxy`.
+- `lcg models` (`-m`): показать доступные модели у текущего провайдера.
+- `lcg health` (`-he`): проверить доступность API провайдера.
+- `lcg config` (`-co`): показать текущую конфигурацию и состояние JWT.
+- `lcg history list` (`-l`): показать историю из JSON‑файла (`LCG_RESULT_HISTORY`).
+- `lcg history view <id>` (`-v`): показать запись истории по `index`.
+- `lcg history delete <id>` (`-d`): удалить запись истории по `index` (с перенумерацией).
+- Флаг `--no-history` (`-nh`) отключает запись истории для текущего запуска и имеет приоритет над `LCG_NO_HISTORY`.
+- `lcg prompts ...` (`-p`): управление системными промптами:
+  - `lcg prompts list` (`-l`) — список всех промптов с содержимым в читаемом формате.
+  - `lcg prompts list --full` (`-f`) — полный вывод содержимого без обрезки длинных строк.
+  - `lcg prompts add` (`-a`) — добавить пользовательский промпт (по шагам в интерактиве).
+  - `lcg prompts delete <id>` (`-d`) — удалить пользовательский промпт по ID (>5).
+- `lcg test-prompt <prompt-id> <описание>` (алиас: `tp`): показать детали выбранного системного промпта и протестировать его на заданном описании.
+- `lcg serve`: запустить HTTP сервер для просмотра сохраненных результатов:
+  - `--port, -p` — порт сервера (по умолчанию из `LCG_SERVER_PORT`)
+  - `--host, -H` — хост сервера (по умолчанию из `LCG_SERVER_HOST`)
+  - `--browser, -b` — открыть браузер автоматически после старта
+  - `--require-auth` — включить аутентификацию (переопределяет `LCG_SERVER_REQUIRE_AUTH`)
+  - `--password` — пароль для аутентификации (переопределяет `LCG_SERVER_PASSWORD`)
+
+### Подробные объяснения (v/vv/vvv)
+
+- `v` — кратко: что делает команда и ключевые опции, без альтернатив.
+- `vv` — средне: назначение, основные ключи, 1–2 примера, кратко об альтернативах.
+- `vvv` — максимально подробно: полный разбор ключей, сценариев, примеры, разбор альтернатив и сравнений.
+
+После вывода подробного объяснения доступно вторичное меню: `Действия: (c)копировать, (s)сохранить, (r)перегенерировать, (n)ничего:`
+
+## Провайдеры
+
+### Ollama (`LCG_PROVIDER=ollama`)
+
+- Требуется запущенный Ollama API (`LCG_HOST`, например `http://localhost:11434/`).
+- `models`, `health` и генерация используют REST Ollama (`/api/tags`, `/api/chat`).
+- API‑ключ не нужен.
+
+### Proxy (`LCG_PROVIDER=proxy`)
+
+- Требуется доступ к прокси‑серверу (`LCG_HOST`) и JWT (`LCG_JWT_TOKEN` или файл `~/.proxy_jwt_token`).
+- Основные эндпоинты: `/api/v1/protected/sberchat/chat` и `/api/v1/protected/sberchat/health`.
+- Команды `update-jwt`/`delete-jwt` помогают управлять токеном локально.
+
+## Рекомендации по выбору провайдера, модели и таймаутов
+
+### Выбор провайдера
+
+- **Ollama**: выбирайте для локальной работы (офлайн/частные данные), когда есть доступ к GPU/CPU и готовность поддерживать локальные модели. Минимальные задержки сети, полная приватность.
+- **Proxy**: выбирайте для централизованного хостинга моделей, более мощных/обновляемых моделей, простоты развёртывания у команды. Обязательно используйте HTTPS и корректный `JWT`.
+
+### Выбор модели
+
+- Для генерации Linux‑команд подходят компактные «code»/«general» модели (по умолчанию `codegeex4`).
+- Для подробных объяснений (`v`/`vv`/`vvv`) точность выше у более крупных моделей (например, семейства LLaMA/Qwen/GigaChat), но они медленнее.
+- Русскоязычные запросы часто лучше обрабатываются в `GigaChat-*` (режим proxy), английские — в популярных open‑source (Ollama).
+- Балансируйте: скорость (малые модели) vs качество (крупные модели). Тестируйте `lcg models` и подбирайте `LCG_MODEL`.
+
+### Таймауты
+
+- Стартовые значения: локально с Ollama — **120–300 сек**, удалённый proxy — **300–600 сек**.
+- Увеличьте таймаут для больших моделей/длинных запросов. Флаг `--timeout` перекрывает `LCG_TIMEOUT` на время запуска.
+- Если часто видите таймауты — проверьте здоровье API (`lcg health`) и сетевую доступность `LCG_HOST`.
+
+### Практические советы
+
+- Если данные чувствительные — используйте Ollama локально и `--no-history` при необходимости.
+- Для «черновой» команды начните с `Ollama + небольшая модель`; для «объяснений и альтернатив» используйте более крупную модель/Proxy.
+- Не вставляйте секреты в запросы. Перед выполнением (`e`) проверяйте команду вручную.
+- Для структуры API см. `API_CONTRACT.md` (эндпоинты и форматы запросов/ответов).
+
+## Поддержка операционных систем
+
+### Автоматическое определение ОС
+
+Приложение автоматически определяет операционную систему и использует соответствующие промпты:
+
+- **Linux/Unix системы** (включая macOS): используются промпты для Linux команд
+- **Windows**: используются промпты для Windows команд (PowerShell, CMD, Batch)
+
+### Промпты для Windows
+
+На Windows системах доступны следующие встроенные промпты:
+
+| ID | Name | Описание |
+| --- | --- | --- |
+| 1 | windows-command | Основной промпт для генерации Windows команд |
+| 2 | windows-command-with-explanation | Промпт с подробным объяснением команд |
+| 3 | windows-command-safe | Безопасный анализ команд с предупреждениями |
+| 4 | windows-command-verbose | Подробный анализ с техническими деталями |
+| 5 | windows-command-simple | Простое и понятное объяснение |
+
+### Примеры использования на Windows
+
+```cmd
+# PowerShell команды
+lcg "хочу получить список всех процессов"
+lcg "показать информацию о дисках"
+
+# CMD команды  
+lcg "создать папку test и перейти в неё"
+lcg "найти все файлы .txt в текущей директории"
+```
+
+## Системные промпты
+
+### Управление промптами
+
+Системные промпты хранятся в папке, указанной в переменной `LCG_PROMPT_FOLDER` (по умолчанию: `~/.config/lcg/gpt_sys_prompts`).
+
+**Логика загрузки:**
+
+- Если файл `sys_prompts` **не существует** — создается файл с системными промптами (ID 1–5) и промптами подробности (ID 6–8)
+- Если файл `sys_prompts` **существует** — загружаются все промпты из файла
+- **Промпты подробности** (v/vv/vvv) сохраняются в том же файле с ID 6, 7, 8
+
+### Встроенные промпты (ID 1–5)
+
+Промпты автоматически выбираются в зависимости от операционной системы:
+
+**Linux/Unix системы:**
+| ID | Name | Описание |
+| --- | --- | --- |
+| 1 | linux-command | «Ответь только Linux‑командой, без форматирования и объяснений». |
+| 2 | linux-command-with-explanation | Сгенерируй команду и кратко объясни, что она делает (формат: COMMAND: explanation). |
+| 3 | linux-command-safe | Безопасные команды (без потери данных). Вывод — только команда. |
+| 4 | linux-command-verbose | Команда с подробными объяснениями флагов и альтернатив. |
+| 5 | linux-command-simple | Простые команды, избегать сложных опций. |
+
+**Windows системы:**
+| ID | Name | Описание |
+| --- | --- | --- |
+| 1 | windows-command | «Ответь только Windows‑командой, без форматирования и объяснений». |
+| 2 | windows-command-with-explanation | Сгенерируй команду и кратко объясни, что она делает (формат: COMMAND: explanation). |
+| 3 | windows-command-safe | Безопасные команды (без потери данных). Вывод — только команда. |
+| 4 | windows-command-verbose | Команда с подробными объяснениями флагов и альтернатив. |
+| 5 | windows-command-simple | Простые команды, избегать сложных опций. |
+
+### Промпты подробности (ID 6–8)
+
+| ID | Name | Описание |
+| --- | --- | --- |
+| 6 | verbose-v | Подробный режим (v) - детальное объяснение команды |
+| 7 | verbose-vv | Очень подробный режим (vv) - исчерпывающее объяснение с альтернативами |
+| 8 | verbose-vvv | Максимально подробный режим (vvv) - полное руководство с примерами |
+
+### Веб-интерфейс управления
+
+Через HTTP сервер (`lcg serve`) доступно полное управление промптами:
+
+- **Просмотр всех промптов** (встроенных и пользовательских)
+- **Редактирование любых промптов** (включая встроенные)
+- **Добавление новых промптов**
+- **Удаление промптов**
+- **Автоматическое сохранение** в файл `sys_prompts`
+
+## Сохранение результатов
+
+При выборе действия `s` ответ сохраняется в `LCG_RESULT_FOLDER` (по умолчанию: `~/.config/lcg/gpt_results`) в файл вида:
+
+```text
+gpt_request_<MODEL>_YYYY-MM-DD_HH-MM-SS.md
+```
+
+## HTTP сервер для просмотра результатов
+
+Команда `lcg serve` запускает веб-сервер для удобного просмотра всех сохраненных результатов:
+
+```bash
+# Запуск с настройками по умолчанию
+lcg serve
+
+# Запуск на другом порту
+lcg serve --port 9090
+
+# Запуск на другом хосте
+lcg serve --host 0.0.0.0 --port 8080
+
+# Автооткрытие браузера (опционально)
+lcg serve --browser
+
+# Использование переменных окружения
+export LCG_SERVER_PORT=3000
+export LCG_SERVER_HOST=0.0.0.0
+lcg serve
+```
+
+### Возможности веб-интерфейса
+
+- **Главная страница** (`/`) — отображает все сохраненные файлы с превью
+- **Статистика** — количество файлов, файлы за последние 7 дней
+- **Просмотр файлов** (`/file/{filename}`) — отображение содержимого конкретного файла
+- **Современный дизайн** — адаптивный интерфейс с карточками файлов
+- **Сортировка** — файлы отсортированы по дате изменения (новые сверху)
+- **Превью содержимого** — первые 200 символов каждого файла
+- **Аутентификация** — защищенный доступ с JWT токенами
+- **CSRF защита** — защита от межсайтовых атак
+- **История запросов** (`/history`) — просмотр истории всех запросов
+- **Управление промптами** (`/prompts`) — редактирование системных промптов
+- **Выполнение команд** (`/run`) — интерактивное выполнение команд
+- **Безопасность** — HTTP-only cookies, проверка токенов
+
+Структура файла (команда):
+
+- `# <заголовок>` — H1, это ваш запрос, при длине >120 символов обрезается до 116 + `...`.
+- `## Prompt` — запрос (включая системный промпт).
+- `## Response` — сгенерированная команда.
+
+Структура файла (подробное объяснение):
+
+- `# <заголовок>` — H1, ваш исходный запрос (с тем же правилом обрезки).
+- `## Prompt` — исходный запрос.
+- `## Command` — первая сгенерированная команда.
+- `## Explanation and Alternatives (model: <MODEL>)` — подробное объяснение и альтернативы.
+
+### Браузер
+
+- По умолчанию UI не открывается автоматически. Для автооткрытия используйте `--browser`.
+- Путь к конкретному браузеру можно задать переменной `LCG_BROWSER_PATH`.
+
+## Выполнение сгенерированной команды
+
+Действие `e` запустит команду через `bash -c`. Перед запуском потребуется подтверждение `y/yes`. Всегда проверяйте команду вручную, особенно при операциях с файлами и сетью.
+
+## Примеры
+
+1. Базовый запрос с Ollama:
+
+```bash
+export LCG_PROVIDER=ollama
+export LCG_HOST=http://localhost:11434/
+export LCG_MODEL=codegeex4
+
+lcg "хочу извлечь linux-command-gpt.tar.gz"
+```
+
+1. Полный ответ от LLM (пример настройки):
+
+```bash
+LCG_PROMPT='Provide full response' LCG_MODEL=codellama:13b \
+  lcg 'i need bash script to execute command by ssh on array of hosts'
+```
+
+1. Proxy‑провайдер:
+
+```bash
+export LCG_PROVIDER=proxy
+export LCG_HOST=http://localhost:8080
+export LCG_MODEL=GigaChat-2
+export LCG_JWT_TOKEN=your_jwt_token_here
+
+lcg "I want to extract linux-command-gpt.tar.gz file"
+
+lcg health
+lcg config
+lcg update-jwt
+```
+
+1. Работа с файлами и промптами:
+
+```bash
+lcg --file ./context.txt "сгенерируй команду jq для выборки поля name"
+lcg --prompt-id 2 "удали все *.tmp в текущем каталоге"
+lcg --sys 1 "показать размер каталога в человеко‑читаемом виде"
+```
+
+1. Диагностика и модели:
+
+```bash
+lcg health
+lcg models
+```
+
+1. HTTP сервер для просмотра результатов:
+
+```bash
+# Запуск сервера
+lcg serve
+
+# Запуск на другом порту
+lcg serve --port 9090
+
+# Запуск на всех интерфейсах
+lcg serve --host 0.0.0.0 --port 8080
+
+# Запуск с аутентификацией
+lcg serve --require-auth --password my_secure_password
+
+# Запуск с переменными окружения
+export LCG_SERVER_REQUIRE_AUTH=true
+export LCG_SERVER_PASSWORD=admin#123456
+lcg serve
+```
+
+## История
+
+`lcg history` выводит историю из JSON‑файла (`LCG_RESULT_HISTORY`), сохраняется между запусками:
+
+```bash
+lcg history list
+```
+
+## Типичные проблемы
+
+- Нет ответа/таймаут: увеличьте `--timeout` или `LCG_TIMEOUT`, проверьте `LCG_HOST` и сетевую доступность.
+- `health` падает: проверьте, что провайдер запущен и URL верный; для `proxy` — что JWT валиден (`lcg config`).
+- Копирование не работает: установите `xclip` или `xsel`.
+- Нет допуска к папке результатов: настройте `LCG_RESULT_FOLDER` или права доступа.
+- Для `ollama`/`proxy` API‑ключ не нужен; команды `update-key`/`delete-key` просто уведомят об этом.
+- HTTP сервер не запускается: проверьте, что порт свободен, используйте `--port` для смены порта.
+- Веб-интерфейс не отображает файлы: убедитесь, что в `LCG_RESULT_FOLDER` есть `.md` файлы.
+- **Аутентификация не работает**: проверьте `LCG_SERVER_REQUIRE_AUTH=true` и правильность пароля.
+- **CSRF ошибки**: убедитесь, что токены передаются в заголовках `X-CSRF-Token`.
+- **Cookies не сохраняются**: проверьте настройки `LCG_DOMAIN` и `LCG_COOKIE_PATH` для reverse proxy.
+- **Kubernetes деплой не работает**: проверьте права доступа к кластеру и наличие всех манифестов.
+
+## JSON‑история запросов
+
+- Путь задаётся `LCG_RESULT_HISTORY` (по умолчанию: `$(LCG_RESULT_FOLDER)/lcg_history.json`).
+- Формат — массив объектов:
+
+```json
+[
+  {
+    "index": 1,
+    "command": "хочу извлечь linux-command-gpt.tar.gz",
+    "response": "tar -xvzf linux-command-gpt.tar.gz",
+    "explanation": "... если запрашивалось v/vv/vvv ...",
+    "system_prompt": "Reply with linux command and nothing else ...",
+    "timestamp": "2025-10-19T13:05:39.000000000Z"
+  }
+]
+```
+
+- Перед новым запросом, если такой уже встречался, будет предложено вывести сохранённый результат из истории с указанием даты.
+- Сохранение в файл истории выполняется автоматически после завершения работы (любое действие, кроме `v|vv|vvv`).
+- При совпадении запроса в истории спрашивается о перезаписи записи.
+- Подкоманды истории работают по полю `index` внутри JSON (а не по позиции массива): используйте `lcg history view <index>` и `lcg history delete <index>`.
+- При показе из истории запрос к API не выполняется: выводится CAPS‑предупреждение и далее доступно обычное меню действий над командой/объяснением.
+
+## Лицензия и исходники
+
+См. README и репозиторий проекта. Предложения и баг‑репорты приветствуются в Issues.
+
+## Доступ к локальному API
+
+### Основные эндпоинты
+
+- `POST /api/execute` — выполнение запросов к LLM
+- `POST /api/save-result` — сохранение результатов
+- `POST /api/add-to-history` — добавление в историю
+- `GET /api/login` — страница аутентификации
+- `POST /api/login` — аутентификация
+- `POST /api/logout` — выход из системы
+- `GET /metrics` — Prometheus метрики
+
+### Примеры использования
+
+```bash
+# Запустить сервер
+lcg serve
+
+# Выполнить запрос (без аутентификации)
+curl -X POST http://localhost:8080/api/execute \
+  -H "Content-Type: application/json" \
+  -A curl \
+  -d '{"prompt": "create directory test", "verbose": "vv"}'
+
+# Аутентификация
+curl -X POST http://localhost:8080/api/login \
+  -H "Content-Type: application/json" \
+  -d '{"username": "admin", "password": "admin#123456"}'
+
+# Выполнение с CSRF токеном
+curl -X POST http://localhost:8080/api/execute \
+  -H "Content-Type: application/json" \
+  -H "X-CSRF-Token: your_csrf_token" \
+  -H "Cookie: auth_token=your_jwt_token" \
+  -d '{"prompt": "create directory test"}'
+```
+
+Подробности и примеры: `API_GUIDE.md`.
+
+## Kubernetes деплой
+
+### Быстрый деплой
+
+```bash
+# Переход в папку деплоя
+cd deploy
+
+# Полный деплой (сборка + деплой + проверка)
+./full-deploy.sh
+
+# Или поэтапно
+./build.sh lcg latest
+./deploy.sh
+./health-check.sh
+```
+
+### Использование Make
+
+```bash
+# Справка
+make help
+
+# Сборка и деплой
+make build
+make deploy
+
+# Мониторинг
+make status
+make logs
+make monitor
+
+# Удаление
+make undeploy
+```
+
+### Flux CD (GitOps)
+
+```bash
+# Настройка Flux CD
+cd deploy/flux
+./setup-flux.sh
+
+# Создание Kustomization
+./create_kustomization.sh
+
+# Мониторинг
+kubectl get kustomization lcg -n flux-system
+```
+
+### Конфигурация для reverse proxy
+
+```bash
+# Настройка для работы за reverse proxy
+export LCG_SERVER_REQUIRE_AUTH=true
+export LCG_SERVER_ALLOW_HTTP=true
+export LCG_DOMAIN=.example.com
+export LCG_COOKIE_PATH=/lcg
+export LCG_COOKIE_SECURE=false
+
+# Запуск
+./lcg serve -H 0.0.0.0 -p 8080
+```
+
+### Мониторинг и безопасность
+
+- **Prometheus метрики**: `/metrics` endpoint
+- **Health checks**: автоматические проверки готовности
+- **HPA**: автоматическое масштабирование (2-10 replicas)
+- **CSRF защита**: токены для всех POST запросов
+- **Аутентификация**: JWT токены в HTTP-only cookies
+- **Security context**: non-root пользователь, минимальные права
+
+Подробности: `deploy/README.md` и `deploy/flux/README.md`.
+
+## Тестирование CSRF защиты
+
+### Автоматическое тестирование
+
+```bash
+# Запуск тестов CSRF защиты
+./test_csrf.sh
+
+# Проверка результатов
+echo "Проверьте вывод на наличие ошибок 403 Forbidden"
+```
+
+### Ручное тестирование
+
+```bash
+# Откройте csrf_test.html в браузере
+open csrf_test.html
+
+# Или используйте curl для тестирования
+curl -X POST http://localhost:8080/api/execute \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": "test"}' \
+  -v
+```
+
+### Демонстрация уязвимости
+
+```bash
+# Откройте csrf_demo.html для демонстрации атаки
+open csrf_demo.html
+```
+
+Подробности: `CSRF_TESTING_GUIDE.md`.