failproofai 1.0.1-beta.1 → 1.0.1

package/.next/standalone/docs-old/ru/agenteye/security.mdx

@@ -0,0 +1,68 @@
+---
+title: "Безопасность"
+description: "Failproof AI Observability разработана для работы рядом с вашими production агентами, что означает, что она видит ваши промпты, входные данные инструментов и результаты их работы."
+---
+
+
+Failproof AI Observability разработана для работы рядом с вашими production агентами, что означает, что она видит ваши промпты, входные данные инструментов и результаты их работы. На этой странице объясняется, как она хранит данные в изолированном виде, под контролем и в ваших руках. Если вы оцениваете Failproof AI Observability для проверки безопасности, начните отсюда.
+
+---
+
+## Ваши данные остаются в вашей среде
+
+Failproof AI Observability развернута локально. События, промпты, ответы модели и аналитика хранятся в ваших собственных базах данных, в вашей собственной среде. Ничто не отправляется на сторонний SaaS для хранения, и ваши данные остаются в вашем облачном аккаунте.
+
+---
+
+## Изоляция между тенантами
+
+Один экземпляр Failproof AI Observability может размещать множество организаций, каждая из которых изолирована на уровне хранилища — это обеспечивается самой базой данных, а не просто интерфейсом:
+
+- Операционные данные организации (пользователи, ключи, панели управления, сохранённые запросы) относятся только к этой организации, и межорганизационное чтение блокируется самой базой данных.
+- Каждое поступившее событие отмечается организацией-владельцем, поэтому события одной организации никогда не могут быть прочитаны другой.
+
+Каждый маршрут панели управления привязан к организации (`/<org-slug>/…`).
+
+---
+
+## Вход в систему
+
+Failproof AI Observability использует вход без пароля, на основе электронной почты. Пароля нет, поэтому нечего фишировать или раскрывать. Пользователь запрашивает одноразовый код (или однокликовую волшебную ссылку), который отправляется ему по электронной почте и быстро истекает. Вход контролируется **списком разрешённых адресов**: только те адреса электронной почты (или домены), которые вы разрешите, смогут пройти проверку подлинности.
+
+![Экран входа Failproof AI Observability, который отправляет одноразовый код на вашу электронную почту](/agenteye/images/login.png)
+
+---
+
+## Ограниченный доступ с помощью API ключей
+
+Каждый клиент проходит проверку подлинности с помощью API ключа, который имеет детализированные разрешения минимальных привилегий. Сборщику нужно только `events:add`; ключ панели управления или помощника может быть только для чтения; деструктивные действия (удаление, переполучение) — это отдельные разрешения, которые вы решаете включить.
+
+![Страница API ключей: разрешения каждого ключа, цветокодированные по областям чтения, записи и деструктивных операций](/agenteye/images/api-keys.png)
+
+Сохраните начальный административный ключ для настройки и выдавайте узкие ключи для всего остального. См. [API ключи](/ru/agenteye/api-keys).
+
+---
+
+## Ассистент только для чтения с одобрением
+
+Встроенный в панель управления [AI ассистент](/ru/agenteye/assistant) отвечает на вопросы по вашим данным, но он ограничен по замыслу:
+
+- Он **предназначен только для чтения по умолчанию**: его SQL проходит через защиту, которая допускает только запросы `SELECT`/`WITH`, однооператорные, с ограничением по строкам.
+- Все, что он создаёт (сохранённый запрос, панель управления), **требует одобрения**: вы проверяете и одобряете каждую запись перед её выполнением.
+- Он **никогда не может удалять**.
+
+Таким образом, коллега может спросить, например, какие агенты дали сбой на этой неделе больше всего, и действовать на основе ответа, при этом ассистент не сможет изменить или удалить ваши данные самостоятельно.
+
+---
+
+## При передаче
+
+Весь трафик передаётся по HTTPS. Вы завершаете TLS своими собственными сертификатами, поэтому трафик от сборщика к серверу и от браузера к серверу зашифрован при передаче.
+
+---
+
+## Следующие шаги
+
+- [Обзор](/ru/agenteye/overview): как Failproof AI Observability работает вместе.
+- [API ключи](/ru/agenteye/api-keys): ограничьте доступ для сборщика, панели управления и ассистента.
+- [Наблюдаемость](/ru/agenteye/observability): что Failproof AI Observability захватывает из ваших агентов.

package/.next/standalone/docs-old/ru/agenteye/sessions.mdx

@@ -0,0 +1,57 @@
+---
+title: "Сессии и граф выполнения"
+description: "Каждое событие из запуска, объединённое в одну читаемую строку и представленное в виде git-подобного графа выполнения, который можно понять за секунды."
+---
+
+
+Хватит гадать, почему запуск не сработал. Failproof AI Observability объединяет все события запуска в одну читаемую строку, а затем рисует весь запуск как git-подобное изображение, которое можно прочитать за секунды. Так вы видите в точности, что сделал ваш агент, шаг за шагом.
+
+![Список сессий: одна строка на запуск, в разных окружениях и агентах, с индикаторами статуса и значками оценки](/agenteye/images/sessions-list.png)
+
+*Одна строка на запуск: индикатор статуса показывает, как закончился запуск с первого взгляда, а значок оценки появляется, когда подключен оценивающий модуль.*
+
+<div style={{ position: "relative", width: "100%", paddingBottom: "56.25%", height: 0, overflow: "hidden", borderRadius: "12px", margin: "1.5rem 0" }}>
+  <iframe src="https://www.youtube.com/embed/VWxukZc5k7s?autoplay=1&mute=1&loop=1&playlist=VWxukZc5k7s&rel=0&playsinline=1" title="Просмотр: отслеживание агента от Failproof AI (2 мин)" allow="autoplay; encrypted-media; picture-in-picture; fullscreen" allowFullScreen style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: 0 }}></iframe>
+</div>
+
+*Отслеживание агента: следите за одним запуском шаг за шагом, от цели к инструментам и к финальному ответу.*
+
+---
+
+## Видьте каждый запуск с первого взгляда
+
+Сырой журнал событий — это правда каждого шага, но когда у вас есть тысячи шагов в десятках запусков, вам нужен запуск, а не шаг. На странице Sessions все события запуска объединяются в одну строку, поэтому день активности превращается в просканируемый список вместо потока данных.
+
+Каждая строка содержит индикатор статуса, поэтому неудачный запуск выделяется среди здоровых задолго до того, как вы что-нибудь нажмёте. Отфильтруйте по диапазону дат, окружению, агенту или сессии, чтобы перейти от «всего» к «нужному мне запуску» в несколько кликов.
+
+Когда вы подключите оценивающий модуль, каждый завершённый запуск автоматически получит оценку, и её последнее значение появится на строке в виде значка. Вы можете отфильтровать по любому диапазону оценок, поэтому «покажи мне все низкооценённые запуски в prod на этой неделе» становится фильтром, а не ручной проверкой. Пока вы его не настроите, сессии всё равно записывают полный запуск — они просто ещё не имеют оценки.
+
+---
+
+## Прочитайте весь запуск как картинку
+
+![Git-подобный граф выполнения сессии рядом с временной шкалой событий, с панелью разбора инструментов, моделей и hooks](/agenteye/images/session-detail.png)
+
+*Граф выполнения (слева) находится рядом с временной шкалой событий; правая панель показывает инструменты, модели, hooks и расход токенов для запуска.*
+
+Кликните на любую сессию, чтобы открыть её граф выполнения: git-подобное представление того, как агенты, инструменты, hooks и вызовы моделей разворачивались во времени. Параллельные под-агенты ветвятся на свои линии, поэтому вы видите, какая работа выполнялась одновременно, какой под-агент завис и где запуск сошёл с курса, не перечитывая логи в уме.
+
+Правая панель даёт вам разбор по запуску: какие инструменты и модели запустились, какие hooks сработали и сколько токенов потратил запуск. Это ответ на вопросы «почему этот запуск стоил так дорого?» или «какой инструмент работает медленно?» прямо рядом с графом, который это вызвал.
+
+Отдельные события имеют адресацию, поэтому вы можете дать кому-то ссылку на один момент вместо «сессия, примерно на две трети вниз». Скопируйте ссылку любого события или следите за ней из [аудита](/ru/agenteye/audits) или ошибки, и сессия откроется с выбранным событием и прокруткой к нему. Это работает даже для очень длинных запусков: временная шкала загружает ограниченное окно для вашего браузера, а ссылка, указывающая за пределы этого окна, всё равно найдёт его событие вместо того, чтобы вернуть вас в начало. Если событие устарело из вашего окна хранения, страница скажет вам об этом вместо того, чтобы молча ничего не выбирать.
+
+---
+
+## Где его найти
+
+Каждая страница приборной панели относится к вашей организации (`/<org-slug>/…`). Sessions находится в разделе **Observe** на левой боковой панели рядом с Events, с фильтрами диапазона дат, окружения, агента и сессии в верхней части списка. Каждая строка находится в одном клике от её полного графа выполнения.
+
+Чтобы включить значки оценок и фильтрацию по диапазону оценок, подключите оценивающий модуль: см. [Evaluations](/ru/agenteye/evaluations).
+
+---
+
+## Связанное
+
+- [Event stream](/ru/agenteye/event-stream): сырой, пошаговый журнал, из которого объединяются все сессии.
+- [Evaluations](/ru/agenteye/evaluations): подключите оценивающий модуль, чтобы каждый запуск получил значок оценки, по которому можно фильтровать.
+- [Telemetry](/ru/agenteye/telemetry): как запуски попадают из вашего агента в эти сессии.

package/.next/standalone/docs-old/ru/agenteye/telemetry.mdx

@@ -0,0 +1,52 @@
+---
+title: "Метрики производительности"
+description: "Заметьте в тот же миг, когда модели, инструменты или хуки замедляются или начинают потреблять ресурсы, и перехватите скачок хвостовой задержки до того, как это почувствуют пользователи."
+---
+
+
+Заметьте в тот же миг, когда модели, инструменты или хуки замедляются или начинают потреблять ресурсы, и перехватите скачок хвостовой задержки до того, как это почувствуют пользователи. Три отдельные страницы превращают сырые временные данные в p50, p95 и p99, которые можно оценить с первого взгляда.
+
+![Страница Models с тепловой картой задержки, полосой процентилей и показателями токенов, стоимости и размера контекстного окна для каждой модели](/agenteye/images/models.png)
+*Страница Models: тепловая карта задержки, полоса процентилей и показатели токенов, расчётная стоимость и коэффициент заполнения контекстного окна.*
+
+## Не позволяйте средним значениям скрывать ваши худшие прогоны
+
+Средняя задержка — утешительна и бесполезна: она скрывает один из пятидесяти вызовов, который зависает и будит дежурного в 2 часа ночи. Страницы Models, Tools и Hooks этого не делают. Каждая имеет одинаковую структуру, поэтому вы разбираетесь один раз:
+
+- **24-позиционная мини-диаграмма** для тренда с первого взгляда: становится ли хуже?
+- **Полоса жизненно важных показателей** с задержками p50, p95 и p99, чтобы типичный прогон и хвостовая часть сидели рядом.
+- **Тепловая карта задержки**, 24 временных интервала на корзины задержек, показывающая, *когда* кластеризовались медленные вызовы.
+- **Полоса процентилей**: линия p50 с затемнёнными лентами p25 до p75 и p10 до p90 и точками p99, чтобы разброс оставался видимым вместо усреднения.
+
+Общий перекрестие при наведении связывает тепловую карту и полосу, поэтому скачок хвоста выравнивается во времени на обоих вместо того, чтобы скрываться за одной средней линией. Найдите все три страницы в разделе **observe** вашей панели управления, каждая ограничена вашей организацией и отфильтрована по диапазону дат, окружению, агенту и сеансу.
+
+## Models: узнайте точно, что каждая модель вам стоит
+
+Страница Models (показана выше) отвечает на два вопроса, которые всегда возникают при получении счёта: какая модель и сколько. Поверх общего представления задержки она добавляет **потребление токенов для каждой модели**, **расчётную стоимость** и **заполнение контекстного окна**, чтобы неконтролируемый рост приглашения и предстоящее сжатие были видны до того, как они вас застанут врасплох.
+
+Failproof AI Observability автоматически распознаёт обычные ID моделей. Если окно выглядит неправильно или вы используете собственную приватную модель, исправьте это или добавьте её в разделе **Settings**, в **model context windows**, и показатели заполнения будут следовать за изменениями.
+
+## Tools: отличите медленное от сломанного
+
+Вызов инструмента может быть медленным или тихо не работать, и вы хотите узнать, что именно происходит, за секунды, а не после раскопок в логах.
+
+![Страница Tools с общей тепловой картой задержки и полосой процентилей рядом с разбивкой по успехам и ошибкам и полосой распределения инструментов](/agenteye/images/tools.png)
+*Страница Tools: одна и та же тепловая карта и полоса процентилей, плюс разбивка по успехам и ошибкам и полоса распределения инструментов.*
+
+Рядом с общим представлением задержки страница Tools добавляет **разбивку по успехам и ошибкам** и **полосу распределения инструментов**, чтобы вы видели с первого взгляда, какими инструментами вы больше всего пользуетесь и какие съедают ваш бюджет ошибок.
+
+## Hooks: точно определите нужный хук и триггер
+
+Когда жизненный цикл хука замедляет прогон, фраза "хуки медленные" — это не то, на что вы можете действовать. Страница Hooks доставляет вас к тому, что имеет значение.
+
+![Страница Hooks с задержкой, разбитой по имени хука и событию-триггеру поверх общей тепловой карты и полосы процентилей](/agenteye/images/hooks.png)
+*Страница Hooks: задержка разбита по имени хука и событию-триггеру.*
+
+На той же тепловой карте задержки и полосе процентилей страница Hooks разбивает активность по **имени хука** и **событию-триггеру**, чтобы вы сосредоточились на одном хуке и одном событии, требующих внимания.
+
+## Связанное
+
+- [Event stream](/ru/agenteye/event-stream): живая, цветовая кодировка всех событий.
+- [Sessions](/ru/agenteye/sessions): свёртывает события в одну строку за прогон и открывает его граф выполнения.
+- [Error tracking](/ru/agenteye/error-tracking): единая поверхность сортировки для всего, что панель управления отмечает красным.
+- [Dashboards](/ru/agenteye/dashboards): сводные представления для всего вашего флота.

package/.next/standalone/docs-old/ru/architecture.mdx

@@ -0,0 +1,333 @@
+---
+---
+title: Архитектура
+description: "Как внутри работают обработчик хука, загрузка конфигурации и оценка политик"
+icon: sitemap
+---
+
+Этот документ объясняет, как работает failproofai изнутри: как система хуков перехватывает вызовы инструментов агента, как загружается и объединяется конфигурация, как вычисляются политики и как приборная панель отслеживает активность агента.
+
+---
+
+## Обзор
+
+failproofai состоит из двух независимых подсистем:
+
+1. **Обработчик хука** — быстрый CLI-подпроцесс, который Claude Code вызывает при каждом вызове инструмента агентом. Вычисляет политики и возвращает решение.
+2. **Монитор агента (приборная панель)** — веб-приложение Next.js для мониторинга сеансов агента и управления политиками.
+
+Обе подсистемы используют одни и те же файлы конфигурации в `~/.failproofai/` и в директории `.failproofai/` проекта, но запускаются как отдельные процессы и взаимодействуют только через файловую систему.
+
+---
+
+## Обработчик хука
+
+### Интеграция с Claude Code
+
+Когда вы запускаете `failproofai policies --install`, в `~/.claude/settings.json` записываются записи вроде этой:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "failproofai --hook PreToolUse"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [ ... ]
+  }
+}
+```
+
+Claude Code затем вызывает `failproofai --hook PreToolUse` как подпроцесс перед каждым вызовом инструмента, передавая JSON-полезную нагрузку на stdin.
+
+### Формат полезной нагрузки
+
+```json
+{
+  "session_id": "abc123",
+  "transcript_path": "/home/user/.claude/projects/myproject/sessions/abc123.jsonl",
+  "cwd": "/home/user/myproject",
+  "permission_mode": "default",
+  "hook_event_name": "PreToolUse",
+  "tool_name": "Bash",
+  "tool_input": { "command": "sudo apt install nodejs" }
+}
+```
+
+Для событий `PostToolUse` полезная нагрузка также содержит `tool_result` с выходом инструмента.
+
+Обработчик устанавливает лимит stdin в 1 МБ. Полезные нагрузки, превышающие этот лимит, отбрасываются и все политики неявно разрешают операцию.
+
+### Формат ответа
+
+**Deny (PreToolUse):**
+```json
+{
+  "hookSpecificOutput": {
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "Blocked by failproofai: sudo command blocked"
+  }
+}
+```
+
+**Deny (PostToolUse):**
+```json
+{
+  "hookSpecificOutput": {
+    "additionalContext": "Blocked by failproofai because: API key detected in output"
+  }
+}
+```
+
+**Instruct (любое событие кроме Stop):**
+```json
+{
+  "hookSpecificOutput": {
+    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
+  }
+}
+```
+
+**Instruct события Stop:**
+- Код выхода: `2`
+- Причина написана в stderr (не stdout)
+
+**Allow:**
+- Код выхода: `0`
+- Пустой stdout
+
+**Allow с сообщением:**
+
+`allow(message)` позволяет политике отправить информационный контекст обратно в Claude, даже когда операция разрешена. Обработчик хука записывает следующий JSON в **stdout** (не в файл конфигурации — это ответ обработчика Claude Code, как и ответы deny и instruct выше):
+
+```json
+// Записано в stdout процессом обработчика хука
+{
+  "hookSpecificOutput": {
+    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
+  }
+}
+```
+- Код выхода: `0` (операция разрешена)
+- Когда несколько политик возвращают `allow` с сообщением, их сообщения объединяются переводами строк в одну строку `additionalContext`
+- Если ни одна политика не предоставляет сообщение, stdout пуст (как и раньше)
+
+### Конвейер обработки
+
+`src/hooks/handler.ts` реализует полный конвейер:
+
+```text
+stdin JSON
+  → разбор полезной нагрузки (макс. 1 МБ)
+  → извлечение метаданных сеанса (session_id, cwd, tool_name, tool_input и т.д.)
+  → readMergedHooksConfig(cwd)    ← объединение конфигурации проекта + локальной + глобальной
+  → регистрация включенных встроенных политик с разрешенными параметрами
+  → загрузка пользовательских политик из customPoliciesPath (если установлено)
+  → регистрация пользовательских политик в реестре политик
+  → вычисление всех политик (встроенные первыми, затем пользовательские)
+      → первый deny прерывает выполнение
+      → решения instruct накапливаются
+      → сообщения allow накапливаются
+  → запись решения JSON в stdout
+  → сохранение события в ~/.failproofai/hook-activity/current.jsonl
+  → выход
+```
+
+Весь процесс выполняется менее чем за 100 мс для типичных полезных нагрузок без LLM-вызовов.
+
+---
+
+## Загрузка конфигурации
+
+`src/hooks/hooks-config.ts` реализует загрузку конфигурации в три области видимости.
+
+```text
+[1] {cwd}/.failproofai/policies-config.json        ← проект  (высший приоритет)
+[2] {cwd}/.failproofai/policies-config.local.json  ← локальная
+[3] ~/.failproofai/policies-config.json             ← глобальная   (низший приоритет)
+```
+
+Логика объединения:
+- `enabledPolicies` — дедублицированное объединение всех трех файлов
+- `policyParams` — ключ для каждой политики, первый файл, который определяет его, побеждает полностью
+- `customPoliciesPath` — первый файл, который определяет его, побеждает
+- `llm` — первый файл, который определяет его, побеждает
+
+Веб-приборная панель использует `readHooksConfig()` (только глобальная) для чтения и записи, так как она не вызывается с cwd проекта.
+
+---
+
+## Вычисление политик
+
+`src/hooks/policy-evaluator.ts` выполняет политики по порядку.
+
+Для каждой политики:
+
+1. Поиск схемы `params` политики (если она есть).
+2. Чтение `policyParams[policy.name]` из объединенной конфигурации.
+3. Объединение предоставленных пользователем значений поверх стандартных значений схемы для получения `ctx.params`.
+4. Вызов `policy.fn(ctx)` с разрешенным контекстом.
+5. Если результат — `deny`, остановиться немедленно и вернуть это решение.
+6. Если результат — `instruct`, накопить сообщение и продолжить.
+7. Если результат — `allow`, перейти к следующей политике.
+
+После выполнения всех политик:
+- Если было возвращено какое-либо `deny`, выдать ответ deny.
+- Если собраны какие-либо возвраты `instruct`, выдать один ответ instruct со всеми сообщениями, объединенными вместе.
+- Иначе выдать ответ allow (пустой stdout, выход 0).
+
+---
+
+## Встроенные политики
+
+`src/hooks/builtin-policies.ts` определяет все 39 встроенных политик как объекты `BuiltinPolicyDefinition`:
+
+```typescript
+interface BuiltinPolicyDefinition {
+  name: string;
+  description: string;
+  fn: (ctx: PolicyContext) => PolicyResult;
+  match: {
+    events: HookEventType[];
+    tools?: string[];
+  };
+  defaultEnabled: boolean;
+  category: string;
+  beta?: boolean;
+  params?: PolicyParamsSchema;
+}
+```
+
+Политики, которые принимают `params`, объявляют `PolicyParamsSchema` с типами и стандартными значениями для каждого параметра. Оценщик политик внедряет разрешенные значения в `ctx.params` перед вызовом `fn`. Функции политик читают `ctx.params` без защиты от null, так как стандартные значения всегда применяются первыми.
+
+Сопоставление шаблонов внутри политик использует разобранные токены команд (argv), а не сопоставление сырых строк. Это предотвращает обход путем инъекции оператора оболочки (например, шаблон для `sudo systemctl status *` не может быть обойден путем добавления `; rm -rf /` к команде).
+
+---
+
+## Пользовательские политики
+
+`src/hooks/custom-hooks-registry.ts` реализует реестр на базе `globalThis`:
+
+```typescript
+const REGISTRY_KEY = "__failproofai_custom_hooks__";
+
+export const customPolicies = {
+  add(hook: CustomHook): void { ... }
+};
+
+export function getCustomHooks(): CustomHook[] { ... }
+export function clearCustomHooks(): void { ... }  // используется в тестах
+```
+
+`src/hooks/custom-hooks-loader.ts` загружает файл политики пользователя:
+
+1. Чтение `customPoliciesPath` из конфигурации; пропуск если отсутствует.
+2. Преобразование в абсолютный путь; проверка существования файла.
+3. Переписывание всех импортов `from "failproofai"` на фактический путь dist, чтобы `customPolicies` разрешалось на тот же реестр `globalThis`.
+4. Рекурсивное переписывание транзитивных локальных импортов для обеспечения совместимости ESM.
+5. Запись временных файлов `.mjs` и `import()` входного файла.
+6. Вызов `getCustomHooks()` для получения зарегистрированных хуков.
+7. Очистка всех временных файлов в блоке `finally`.
+
+При любой ошибке (файл не найден, синтаксическая ошибка, ошибка импорта) ошибка записывается в `~/.failproofai/hook.log` и загрузчик возвращает пустой массив. Встроенные политики не затрагиваются.
+
+Пользовательские политики вычисляются после всех встроенных политик. `deny` пользовательской политики все еще прерывает дальнейшие пользовательские политики (но все встроенные уже выполнены к этому времени).
+
+---
+
+## Логирование активности
+
+После каждого события хука обработчик добавляет строку JSONL в `~/.failproofai/hook-activity/current.jsonl`, которая ротирует в `page-<timestamp>-<seq>.jsonl` после достижения размера страницы:
+
+```json
+{
+  "timestamp": "2026-04-06T12:34:56.789Z",
+  "sessionId": "abc123",
+  "eventType": "PreToolUse",
+  "toolName": "Bash",
+  "policyName": "block-sudo",
+  "decision": "deny",
+  "reason": "sudo command blocked by failproofai",
+  "durationMs": 12
+}
+```
+
+Одна строка на политику, которая приняла решение не-allow. Решения allow не логируются (чтобы файл оставался небольшим).
+
+---
+
+## Архитектура приборной панели
+
+Приборная панель — это приложение **Next.js 16** с использованием App Router с React Server Components и Server Actions.
+
+```text
+app/
+  layout.tsx                  ← Корневой макет (тема, телеметрия, навигация)
+  projects/page.tsx           ← Компонент сервера: список всех проектов Claude
+  project/[name]/page.tsx     ← Компонент сервера: список сеансов в проекте
+  project/[name]/session/
+    [sessionId]/page.tsx      ← Компонент сервера: рендеринг просмотра сеанса
+  policies/page.tsx           ← Компонент клиента: управление политиками + журнал активности
+  actions/
+    get-hooks-config.ts       ← Чтение конфигурации + список политик
+    update-hooks-config.ts    ← Включение/отключение политики
+    update-policy-params.ts   ← Обновление параметров политики
+    get-hook-activity.ts      ← Разбиение на страницы/поиск в журнале активности
+    install-hooks-web.ts      ← Установка/удаление хуков из браузера
+  api/
+    download/[project]/[session]/route.ts   ← Экспорт по сеансу CLI (JSONL или JSON)
+```
+
+**Поток данных:**
+
+- Компоненты страницы вызывают `lib/projects.ts` и `lib/log-entries.ts` для прямого чтения данных проекта/сеанса из файловой системы (нет API-слоя для чтения).
+- Страница политик использует Server Actions для всех изменений (переключение, обновление параметров, установка/удаление).
+- Просмотр сеанса разбирает формат JSONL-транскрипта Claude и рендерит временную шкалу сообщений и вызовов инструментов.
+
+**Ключевые решения по дизайну:**
+
+- Нет базы данных — все постоянное состояние хранится в простых файлах (`~/.failproofai/`, `~/.claude/projects/`).
+- Server Actions для изменений — REST API не требуется для операций CRUD.
+- React Server Components для страниц чтения — более быстрая первоначальная загрузка, отсутствие клиентского пакета для получения данных.
+- Клиентские компоненты только там, где требуется интерактивность (переключатели политик, поиск в активности, просмотр журнала).
+
+---
+
+## Макет файлов
+
+```text
+failproofai/
+├── bin/
+│   └── failproofai.mjs           # CLI маршрутизатор (hook / dashboard / install / и т.д.)
+├── src/hooks/
+│   ├── handler.ts                # Конвейер события хука
+│   ├── builtin-policies.ts       # 39 определений политик
+│   ├── policy-evaluator.ts       # Двигатель выполнения политик
+│   ├── policy-registry.ts        # Регистрация и поиск политик
+│   ├── policy-types.ts           # Интерфейсы TypeScript
+│   ├── hooks-config.ts           # Загрузка конфигурации в несколько областей видимости
+│   ├── custom-hooks-registry.ts  # Реестр хуков на базе globalThis
+│   ├── custom-hooks-loader.ts    # ESM-загрузчик для пользовательских JS-хуков
+│   ├── manager.ts                # Операции install / remove / list
+│   ├── install-prompt.ts         # Интерактивное приглашение выбора политики
+│   ├── hook-logger.ts            # Логирование в hook.log
+│   ├── hook-activity-store.ts    # Сохранение активности в hook-activity/
+│   └── llm-client.ts             # LLM API клиент (для политик с AI-поддержкой)
+├── app/                          # Приборная панель Next.js (страницы + server actions)
+├── lib/                          # Общие утилиты
+│   ├── projects.ts               # Перечисление проектов Claude из файловой системы
+│   ├── log-entries.ts            # Разбор формата Claude JSONL-транскрипта
+│   ├── paths.ts                  # Разрешение системных путей
+│   └── ...
+├── components/                   # Общие компоненты React UI
+├── contexts/                     # Поставщики контекста React (тема, автообновление, телеметрия)
+├── examples/                     # Примеры файлов пользовательских хуков
+└── __tests__/                    # Модульные и E2E тесты
+```