refactor: refactor foundation

docs/API-LAYER.md

@@ -1,8 +1,12 @@
 # API Layer
 
-OpenAPI backend является источником истины. После изменения backend-контракта запускается `npm run openapi:generate`; `src/shared/api/generated/schema.d.ts` не редактируется вручную.
+OpenAPI backend является источником истины. После изменения backend-контракта запускается `npm run openapi:sync`; она получает опубликованный документ, валидирует генерацией и только затем атомарно обновляет `src/shared/api/spec/openapi.json` и `src/shared/api/generated/schema.d.ts`. Оба файла committed; generated файл не редактируется вручную.
 
-Все HTTP-вызовы используют `apiClient` из `src/shared/api`. Прямой `fetch` в features, pages и entities не используется.
+`npm run openapi:generate` и `npm run openapi:check` используют snapshot offline. `verify` никогда не требует backend; OpenAPI endpoint разрешён только явной sync-команде.
+
+Все HTTP-вызовы используют `apiClient` и `apiQueryClient` из `src/shared/api`. Прямой `fetch` в features, pages и entities не используется. Query options берутся из `apiQueryClient`, а сохранённые cache keys и policies задаются вызывающим slice.
+
+Bearer header принадлежит только shared authenticated fetch. Auth endpoints исключены; refresh сохраняет single-flight и один retry `UNAUTHORIZED`. Не передавайте `Authorization` из query или mutation.
 
 Request и response types выводятся из generated `paths`, например:
 

docs/CONVENTIONS.md

@@ -8,6 +8,8 @@
 - Zod-схемы не содержат пользовательских строк: использовать `validationMessage(key)` из `src/shared/i18n/zod.ts`.
 - Публичный импорт слайса идёт через его `index.ts`.
 - Тесты лежат рядом с исходником как `*.test.tsx`.
+- Зависимости используют exact versions; не добавлять semver ranges.
+- Полный локальный gate: `npm run verify`. Pre-commit запускает staged formatting, OpenAPI check и FSD dependency checks; commit message должен следовать Conventional Commits.
 
 ## File roles
 

docs/STRUCTURE.md

@@ -9,3 +9,5 @@
 - `shared` - переиспользуемый код без доменной логики: API, i18n и UI.
 
 Каждый слайс предоставляет наружу только public API через `index.ts`; внутренние файлы соседний слой не импортирует напрямую.
+
+Для cross-slice imports используйте alias `@/` и public API, например `@/entities/portfolio`. Vite и TypeScript используют одинаковый alias.

docs/TESTING.md

@@ -1,5 +1,7 @@
 # Testing
 
-Тесты запускаются `npm run test:run` через Vitest и Testing Library.
+Тесты запускаются `npm run test:run` через Vitest и Testing Library. `npm run test:coverage` создаёт локальный coverage report.
+
+MSW запускается только Vitest setup в `src/test/`; handlers покрывают текущий API. Не добавлять service worker, browser mocking или mock development mode. Для transport проверять заголовки и retry через MSW, не через реальный backend.
 
 Проверяйте наблюдаемое поведение, а не детали реализации. UI-тест строится как Arrange, Act, Assert; для интерактивных действий предпочитайте `userEvent`. Форма должна проверять валидацию и отсутствие запроса при невалидных данных; маршруты - редиректы и доступность экрана.