Update knowledge base

.claude/development/commands.md

@@ -0,0 +1,56 @@
+# Commands Reference
+
+## Запуск worker
+
+FrankenPHP стартует PHP-воркеры через Caddyfile:
+
+```bash
+frankenphp run --config Caddyfile
+```
+
+Воркер-скрипт приложения подключается к фреймворку через `WorkerRunner`:
+
+```php
+// worker.php
+$runner = new WorkerRunner($kernel);
+$runner->run();
+```
+
+---
+
+## Console-команды
+
+```bash
+php bin/console <command> [options]
+```
+
+Команды регистрируются в контейнере как сервисы с тегом (см. `architecture/console.md`).
+
+---
+
+## Composer
+
+```bash
+composer install          # Установить зависимости из lock
+composer update           # Обновить зависимости
+composer dump-autoload    # Пересоздать autoloader
+```
+
+---
+
+## Docker (если используется в приложении)
+
+```bash
+docker compose up -d      # Запустить сервисы
+docker compose build      # Пересобрать образ
+docker compose logs -f    # Логи в реальном времени
+```
+
+---
+
+## Git shortcuts
+
+```bash
+# Создать task-файл для новой ветки
+cp .claude/tasks/_template.md .claude/tasks/active/<branch-name>.md
+```

.claude/development/conventions.md

@@ -0,0 +1,75 @@
+# Conventions
+
+## Commit Messages
+
+```
+[type] Краткое описание в imperative form
+```
+
+Примеры:
+- `Add autoload for routes and services`
+- `Fix missing CORS config exception`
+- `Refactor WorkerRunner startup sequence`
+
+---
+
+## Branch Naming
+
+| Тип | Паттерн | Пример |
+|-----|---------|--------|
+| Feature | `feature/description` | `feature/jwt-refresh` |
+| Fix | `fix/description` | `fix/cors-header` |
+| Refactor | `refactor/description` | `refactor/kernel-bootstrap` |
+| Knowledge base / tooling | `kebab-case` | `knowledge-base` |
+
+---
+
+## PHP Namespaces
+
+| Компонент | Namespace |
+|-----------|-----------|
+| Core | `Pronchev\Pinecore\` |
+| HTTP | `Pronchev\Pinecore\Http\` |
+| Auth | `Pronchev\Pinecore\Auth\` |
+| ORM | `Pronchev\Pinecore\Orm\` |
+| Log | `Pronchev\Pinecore\Log\` |
+| Console | `Pronchev\Pinecore\Console\` |
+| Model | `Pronchev\Pinecore\Model\` |
+
+---
+
+## File & Class Naming
+
+- PSR-4: файл = имя класса, PascalCase (`WorkerRunner.php` содержит `class WorkerRunner`)
+- Атрибуты ORM: PascalCase (`#[Collection]`, `#[Field]`)
+- Interfaces: суффикс `Interface` (`MiddlewareInterface`)
+
+---
+
+## Работа с задачами (.claude/tasks/)
+
+При старте новой ветки:
+```bash
+cp .claude/tasks/_template.md .claude/tasks/active/<branch-name>.md
+```
+
+Правила:
+1. Во время разработки — редактируй только свой task-файл
+2. Можно добавить `decisions/ADR-NNN.md` (новый файл — нет конфликтов)
+3. Не трогай `architecture/` и `development/` — только в main
+
+При мерже в main:
+- Читай секцию "Merge Notes" в task-файле
+- Обновляй стабильные docs если нужно
+- Перемести: `tasks/active/<branch>.md` → `tasks/completed/<branch>.md`
+
+---
+
+## Когда писать ADR
+
+Создай `decisions/ADR-NNN-title.md` когда:
+- Вводится новый архитектурный паттерн
+- Принято нетривиальное решение (и кто-то может спросить "почему так?")
+- Отвергнута очевидная альтернатива
+
+ADR — только новые файлы, никогда не правь существующие.

.claude/development/patterns.md

@@ -0,0 +1,111 @@
+# Code Patterns
+
+Переиспользуемые паттерны кодовой базы. Используй существующие — не изобретай новые без необходимости.
+
+---
+
+## 1. Kernel — статический контейнер
+
+```php
+// Инициализация (один раз при старте воркера)
+Kernel::init($container);
+
+// Получение сервиса
+$service = Kernel::getContainer()->get(MyService::class);
+```
+
+Kernel хранит единственный инстанс контейнера на весь процесс воркера.
+
+---
+
+## 2. ContainerFactory — сборка контейнера
+
+```php
+$factory = new ContainerFactory($config, $environment);
+$container = $factory->build();
+```
+
+Autoload: все файлы из `routes/` и `services/` подхватываются автоматически.
+Не регистрируй маршруты и сервисы вручную в `index.php` — кладёт файлы в соответствующие директории.
+
+---
+
+## 3. Router и RouteDefinition
+
+```php
+// routes/api.php
+return [
+    new RouteDefinition('GET', '/users/{id}', UserController::class, 'show'),
+];
+```
+
+Router находит нужный маршрут по методу и пути, извлекает параметры и вызывает контроллер.
+
+---
+
+## 4. Middleware — цепочка обработки запроса
+
+```php
+class MyMiddleware implements MiddlewareInterface {
+    public function handle(Request $request, callable $next): Response {
+        // до
+        $response = $next($request);
+        // после
+        return $response;
+    }
+}
+```
+
+Middleware регистрируются в контейнере и применяются ко всем запросам в воркере.
+
+---
+
+## 5. ORM — атрибуты сущностей
+
+```php
+#[Collection('users')]
+class UserEntity {
+    #[Field('_id')]
+    public string $id;
+
+    #[Field('name')]
+    public string $name;
+}
+```
+
+Repository наследует базовый класс и получает методы `find`, `findOne`, `save`, `delete` из коробки.
+
+---
+
+## 6. JWT Auth
+
+```php
+// AuthMiddleware автоматически валидирует Bearer-токен
+// В контроллере — получить текущего пользователя из request
+$user = $request->getAttribute('user');
+```
+
+`JwtService` отвечает за выпуск и верификацию токенов. Конфиг: секрет и TTL через `Config`.
+
+---
+
+## 7. Config — конфигурация
+
+```php
+$value = Config::get('key');
+$value = Config::get('section.key', $default);
+```
+
+Конфиг загружается из `environment.php` (или `.env`). Доступен глобально через статический метод.
+
+---
+
+## 8. WorkerRunner — цикл обработки запросов
+
+```php
+// Внутри worker.php
+$runner = new WorkerRunner($kernel);
+$runner->run(); // FrankenPHP loop: запрос → роутинг → middleware → контроллер → ответ
+```
+
+`WorkerRunner` перехватывает исключения и возвращает корректный HTTP-ответ даже при ошибке.

.claude/development/testing.md

@@ -0,0 +1,61 @@
+# Testing & Debugging
+
+## Запуск воркера локально
+
+```bash
+frankenphp run --config Caddyfile
+```
+
+Убедись, что переменные окружения заданы (`.env` или `environment.php`).
+
+---
+
+## Отладка запросов
+
+Включи подробное логирование через конфиг:
+
+```php
+Config::get('log.level') // DEBUG для максимального вывода
+```
+
+Логи пишутся через `LoggerInterface` (Monolog). Смотри `architecture/logging.md` для деталей.
+
+---
+
+## Частые проблемы
+
+### Воркер не стартует
+
+- Проверь синтаксис `Caddyfile` и путь до `worker.php`
+- FrankenPHP требует `FRANKENPHP_CONFIG` или явного указания воркер-скрипта
+- Проверь, что `Kernel::init()` вызван до первого запроса
+
+### Маршрут не найден (404)
+
+- Убедись, что файл с `RouteDefinition` лежит в `routes/` (autoload подхватывает автоматически)
+- Проверь HTTP-метод и путь: параметры вида `{id}` чувствительны к паттерну
+
+### JWT не валидируется
+
+- Проверь, что `Config::get('auth.secret')` не пустой
+- Убедись, что `AuthMiddleware` зарегистрирован в контейнере
+- Время жизни токена — `Config::get('auth.ttl')`
+
+### Ошибка CORS
+
+- `CorsMiddleware` требует явного конфига (список разрешённых origins)
+- Если конфиг не задан — бросается `RuntimeException` при старте
+
+### MongoDB не подключается
+
+- Проверь DSN в конфиге: `Config::get('mongodb.dsn')`
+- Проверь, что MongoDB-сервис запущен и доступен из воркера
+
+---
+
+## Инспекция контейнера
+
+```php
+// В dev-режиме: посмотреть все зарегистрированные сервисы
+$ids = Kernel::getContainer()->getServiceIds();
+```