main

2026-05-20 19:33:02 +03:00
commit f4bca8449e
30 changed files with 4152 additions and 0 deletions
@@ -0,0 +1,178 @@
+# ZBrain — Claude Code Context
+
+Этот файл читается Claude Code при работе в репозитории ZBrain. Описывает контекст проекта, конвенции, и где что искать.
+
+## Что это за проект
+
+ZBrain — централизованная база знаний для AI-агентов ZETIT. Это:
+- **Веб-админка** для управления несколькими gbrain instance'ами
+- **MCP-прокси** между Claude Code и gbrain с auth, rate limit, audit
+- **Многотенантная архитектура** с изоляцией БД на каждый брейн
+
+Полное описание — в [README.md](README.md), архитектура — в [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
+## Контекст пользователя
+
+Этот проект разрабатывается **Зуевым Алексеем (ZETIT, ИП)**. Окружение:
+- **Продакшен серверы** работают на Ubuntu 22.04
+- **Сеть** — за FNA-прокси (`fna.zetit.ru:3128`, логин `client_001`)
+- **Git** — на git.zetit.ru (внутренний). Этот репо: `git@git.zetit.ru:zuevav/ZBrain.git`
+- **gbrain** — vendored mirror на `git@git.zetit.ru:zuevav/gbrain-mirror.git`
+- **Параллельные проекты** — ZetitConnect (тоже Node/React/Postgres), TeleraPharma инфра, личные проекты
+- **Стиль работы** — детальные spec'и + поэтапная реализация через Claude Code
+
+## Технологический стек
+
+| Слой | Технология |
+|------|-----------|
+| Backend runtime | Node.js 22 LTS + TypeScript 5.6 |
+| Backend framework | Express 4 |
+| ORM | Drizzle ORM |
+| Frontend | React 18 + Vite + TypeScript |
+| Styling | Tailwind CSS + shadcn/ui |
+| State | React Query + Zustand |
+| Forms | React Hook Form + Zod |
+| DB | PostgreSQL 16 + pgvector |
+| Auth | passport.js (local + yandex + github) |
+| Package manager | bun (workspaces) |
+| Testing | Vitest |
+| Deployment | Docker Compose + systemd для gbrain instances |
+
+## Структура репозитория
+
+```
+ZBrain/
+├── apps/
+│   ├── api/                # Backend Express app
+│   │   └── src/
+│   │       ├── routes/     # HTTP routes
+│   │       ├── services/   # бизнес-логика
+│   │       ├── middleware/ # auth, RBAC, rate limit
+│   │       ├── db/         # Drizzle schema и миграции
+│   │       └── lib/        # утилиты
+│   └── web/                # Frontend React app
+│       └── src/
+│           ├── pages/      # страницы (роуты)
+│           ├── components/ # переиспользуемые компоненты
+│           ├── hooks/      # React hooks
+│           └── api/        # клиент к /api
+├── packages/
+│   ├── shared/             # типы и схемы общие для api+web
+│   └── mcp-proxy/          # MCP proxy (валидация токенов, rate limit, audit)
+├── deploy/                 # Docker, systemd, nginx конфиги
+├── docs/                   # документация
+└── scripts/                # bash скрипты для VM
+```
+
+## Конвенции кода
+
+### TypeScript
+
+- `strict: true`, `noUncheckedIndexedAccess: true`
+- Все API ответы типизированы через `@zbrain/shared` types
+- Все request bodies валидируются через Zod schemas из `@zbrain/shared`
+- Никаких `any` без `// FIXME` комментария
+
+### Express routes
+
+```typescript
+// apps/api/src/routes/brains.ts
+import { Router } from 'express';
+import { requireAuth, requireRole } from '../middleware/auth.js';
+import { CreateBrainSchema } from '@zbrain/shared';
+
+export const brainsRouter = Router();
+
+brainsRouter.get('/', requireAuth, async (req, res) => {
+  const brains = await brainService.list(req.user);
+  res.json({ items: brains });
+});
+
+brainsRouter.post('/', requireAuth, requireRole(['owner', 'admin']), async (req, res) => {
+  const body = CreateBrainSchema.parse(req.body);
+  const brain = await brainService.create(body, req.user);
+  res.status(201).json(brain);
+});
+```
+
+### React components
+
+- Functional components с hooks (без class components)
+- Props типизированы через interface
+- Используем shadcn/ui компоненты, не пишем свои базовые (Button, Input)
+- React Query для всех server-state, Zustand только для UI state
+
+### Стиль ошибок
+
+```typescript
+// API возвращает структуру ApiError из @zbrain/shared
+res.status(400).json({
+  error: 'Validation failed',
+  code: 'VALIDATION_ERROR',
+  details: zodError.flatten(),
+});
+```
+
+## Что точно делать НЕ надо
+
+- **НЕ обращаться к gbrain напрямую из Claude Code** — только через brainhub-proxy
+- **НЕ хранить токены в plain text** — всегда хеш SHA-256
+- **НЕ логировать секреты** — пароли, токены, API ключи никогда не в logs
+- **НЕ создавать прямые SQL запросы** — только через Drizzle ORM
+- **НЕ забывать про audit log** для любых мутаций
+- **НЕ забывать про RBAC** — каждый mutate endpoint проверяет роль
+- **НЕ выставлять admin API на публичный порт 3010** — только /mcp и /oauth
+
+## Что делать ВСЕГДА
+
+- Перед началом нового спринта читать [docs/ROADMAP.md](docs/ROADMAP.md)
+- Перед написанием нового API endpoint смотреть в [packages/shared/src/types.ts](packages/shared/src/types.ts) — может тип уже есть
+- При изменении схемы БД — миграция через Drizzle, не вручную в Postgres
+- При добавлении нового permission/role — обновлять [docs/SECURITY.md](docs/SECURITY.md)
+- При нестандартном архитектурном решении — создавать ADR в [docs/DECISIONS/](docs/DECISIONS/)
+- Закоммитить миграции и schema файлы вместе с кодом, который их использует
+- Тесты для критичной логики (auth, MCP proxy, RBAC). UI можно без unit тестов в первой версии.
+
+## Полезные команды
+
+```bash
+# Установка
+bun install
+
+# Локальная разработка (запустить Postgres сначала)
+docker compose -f deploy/docker/docker-compose.dev.yml up -d
+bun run db:migrate
+bun run dev
+
+# Миграции
+bun run --cwd apps/api drizzle-kit generate
+bun run db:migrate
+
+# Запуск API + Web в watch mode
+bun run dev
+
+# Production build
+bun run build
+
+# Тесты
+bun run test
+```
+
+## Текущее состояние
+
+> Обновляй этот раздел после каждого закрытого спринта.
+
+- [x] **S0**: Инфраструктура VM (bootstrap скрипт готов)
+- [ ] **S1**: Первый gbrain instance (create-brain.sh готов, нужно тестирование)
+- [ ] **S2**: Brainhub каркас + локальный auth
+- [ ] **S3**: MCP Proxy + Tokens
+- [ ] **S4**: CRUD брейнов + источники + sync
+- [ ] **S5**: Dashboard + Projects + Connect
+- [ ] **S6**: OAuth + публичный контур
+- [ ] **S7**: Hardening
+
+## Связанные проекты
+
+- **gbrain** (vendored) — https://github.com/garrytan/gbrain (mirror в git.zetit.ru/zuevav/gbrain-mirror)
+- **ZetitConnect** — паттерны переиспользуем (Node/Express/React/Postgres стек)
+- **ZetitClaude Code setup** — FNA proxy конфигурация, tmux/zsh wrappers
@@ -0,0 +1,162 @@
+# INSTALL — Что делать после клонирования репозитория
+
+Этот документ — единая точка входа после `git clone git@git.zetit.ru:zuevav/ZBrain.git`. Здесь только команды и checkpoints, без объяснений (объяснения — в `docs/`).
+
+## Предусловия
+
+- [ ] Виртуалка создана: **Ubuntu 22.04 LTS, 4 vCPU, 8 GB RAM, 80 GB SSD**
+- [ ] SSH-доступ настроен
+- [ ] Внутренний DNS `brain.zetit.local` указывает на эту VM
+- [ ] (Опционально) Внешний DNS `brain.zetit.ru` указывает на edge-сервер или эту VM
+- [ ] Создан **mirror gbrain** в твоём git:
+  ```bash
+  # на любой машине с GitHub доступом, ОДИН РАЗ
+  git clone --mirror https://github.com/garrytan/gbrain.git
+  cd gbrain.git
+  git push --mirror git@git.zetit.ru:zuevav/gbrain-mirror.git
+  ```
+
+## Шаг 1 — Bootstrap VM
+
+```bash
+# На VM
+sudo mkdir -p /opt && sudo chown $USER:$USER /opt
+git clone git@git.zetit.ru:zuevav/ZBrain.git /opt/zbrain
+cd /opt/zbrain
+
+# Запуск (правь параметры под себя!)
+sudo TOTAL_RAM_GB=8 \
+     FNA_PROXY="http://client_001:ВСТАВЬ_ПАРОЛЬ@fna.zetit.ru:3128" \
+     GBRAIN_REPO="https://git.zetit.ru/zuevav/gbrain-mirror.git" \
+     GBRAIN_VERSION="master" \
+     bash scripts/bootstrap-vm.sh
+```
+
+**Проверка:** последняя строчка вывода — "Bootstrap готов" + список Next Steps.
+
+## Шаг 2 — Postgres пароли
+
+```bash
+sudo -u postgres psql
+```
+
+```sql
+ALTER USER postgres PASSWORD 'СГЕНЕРИРОВАТЬ_24_СИМВОЛА';
+CREATE USER brainhub WITH PASSWORD 'ДРУГИЕ_24_СИМВОЛА';
+GRANT ALL PRIVILEGES ON DATABASE brainhub TO brainhub;
+\q
+```
+
+**Сохрани оба пароля в KeePass!**
+
+## Шаг 3 — Заполнить `.env`
+
+```bash
+sudo cp /etc/zbrain/env.example /etc/zbrain/.env
+sudo chmod 600 /etc/zbrain/.env
+sudo chown zbrain:zbrain /etc/zbrain/.env
+
+# Сгенерировать секреты
+echo "SESSION_SECRET=$(openssl rand -hex 32)"
+echo "JWT_SECRET=$(openssl rand -hex 32)"
+echo "TOKEN_ENCRYPTION_KEY=$(openssl rand -hex 16)"
+
+sudo nano /etc/zbrain/.env
+```
+
+Заполнить:
+- `DATABASE_URL` — с паролем brainhub из шага 2
+- `HTTPS_PROXY`, `HTTP_PROXY` — с реальным паролем FNA
+- `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`
+- Секреты из openssl выше
+- `INITIAL_OWNER_EMAIL`, `INITIAL_OWNER_PASSWORD`
+
+## Шаг 4 — Первый брейн
+
+```bash
+sudo bash /opt/zbrain/scripts/create-brain.sh zetit "ZETIT MSP" 3001
+```
+
+**Проверка:**
+
+```bash
+sudo systemctl status zbrain-gbrain-zetit
+curl -s http://localhost:3001/health || curl -s http://localhost:3001/
+```
+
+## Шаг 5 — Тестовый импорт
+
+Подготовь любую папку с markdown-файлами и:
+
+```bash
+sudo -u zbrain bash -c '
+  export PATH=$HOME/.bun/bin:$PATH
+  source /etc/zbrain/.env
+  export DATABASE_URL=$(jq -r .database_url /var/lib/zbrain/brains/zetit/config.json)
+  cd /var/lib/zbrain/gbrain
+  bun run gbrain import /tmp/test-markdown/
+'
+```
+
+**Проверка:**
+
+```bash
+sudo -u postgres psql -d gbrain_zetit -c '
+SELECT
+  (SELECT count(*) FROM pages) AS pages,
+  (SELECT count(*) FROM content_chunks) AS chunks,
+  (SELECT count(*) FROM content_chunks WHERE embedding IS NOT NULL) AS embedded;
+'
+```
+
+Если `embedded < chunks` — embeddings ещё генерируются (проверь логи) или OPENAI_API_KEY не работает (проверь curl через FNA proxy).
+
+## Шаг 6 — Опционально: подключить Claude Code напрямую
+
+Пока brainhub не написан (Sprint 2+), можно подключиться к gbrain через SSH-туннель:
+
+```bash
+# С твоей машины
+ssh -L 3001:127.0.0.1:3001 admin@<vm-ip>
+```
+
+В `~/.claude/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "zbrain-zetit-direct": {
+      "transport": "http",
+      "url": "http://127.0.0.1:3001"
+    }
+  }
+}
+```
+
+Перезапустить Claude Code, проверить MCP инструменты.
+
+После Sprint 2-3 эта прямая связь будет заменена на `https://brain.zetit.ru/mcp/zetit` с токеном.
+
+## Что дальше
+
+См. **[docs/ROADMAP.md](docs/ROADMAP.md)** — план по спринтам.
+
+Следующая большая задача — **Sprint 2**: каркас brainhub с auth и UI. Это уже работа в коде:
+
+```bash
+cd /opt/zbrain
+claude  # запустить Claude Code в репо
+# В Claude Code:
+# > Прочитай CLAUDE.md и docs/ROADMAP.md, начнём Sprint 2.
+```
+
+## Если что-то пошло не так
+
+См. **[docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)** раздел "Типовые проблемы" и **[docs/OPERATIONS.md](docs/OPERATIONS.md)** раздел "Runbook'и инцидентов".
+
+Логи везде:
+- bootstrap: stdout скрипта + `/var/log/syslog`
+- Postgres: `/var/log/postgresql/postgresql-16-main.log`
+- gbrain: `journalctl -u zbrain-gbrain-<name>` и `/var/log/zbrain/<name>.log`
+- brainhub (когда будет): `/var/log/zbrain/brainhub.log`
+- nginx: `/var/log/nginx/zbrain-*.log`
@@ -0,0 +1,12 @@
+Copyright (c) 2026 ZETIT (ИП Зуев Алексей Викторович). All rights reserved.
+
+Proprietary and confidential.
+
+Unauthorized copying of this repository, via any medium, is strictly prohibited
+without express written permission from the copyright holder.
+
+This software depends on third-party components, including:
+- gbrain (https://github.com/garrytan/gbrain) — MIT License
+- Other open-source libraries as declared in package.json files
+
+These components retain their original licenses and copyright notices.
@@ -0,0 +1,173 @@
+# ZBrain
+
+Централизованная база знаний для AI-агентов ZETIT. Веб-админка + MCP-прокси поверх [gbrain](https://github.com/garrytan/gbrain).
+
+## Зачем это
+
+У нас много разных контекстов, и каждый Claude Code инстанс сейчас читает документацию с диска целиком при каждом запросе:
+
+- **ZetitConnect MSP** — спецификации, спринты, архитектура
+- **TeleraPharma** — runbook'и по Exchange, MikroTik, FortiGate, 1C
+- **ZETIT клиенты** — конфигурации, инциденты, скрипты
+- **Personal** — личные проекты, недвижимость, авто
+- **Community (Смоленская 10)** — общедомовое, ЖКХ
+
+ZBrain даёт единую точку доступа: гибридный семантический поиск по корпусу, MCP-интеграция с Claude Code/Cursor, разделение по доменам с изоляцией доступа.
+
+## Архитектура
+
+```
+                          ИНТЕРНЕТ
+                              │
+                              ↓
+              brain.zetit.ru (nginx, TLS, OAuth)
+                              │
+              ┌───────────────┴────────────────┐
+              │     brainhub-public            │
+              │   - OAuth 2.1 (PKCE)           │
+              │   - токены с scope             │
+              │   - rate limit                 │
+              │   - audit log                  │
+              └───────────────┬────────────────┘
+                              │
+══════════════════════════════╪═══════════════════════════════
+                  VPN / внутренний контур
+                              │
+              ┌───────────────┴────────────────┐
+              │     brainhub-internal          │
+              │   - Web UI (React)             │
+              │   - Admin API                  │
+              │   - MCP proxy router           │
+              │   - SSE event aggregator       │
+              └───────┬────────────┬───────────┘
+                      │            │
+              ┌───────┴────────────┴──────────┐
+              │   gbrain instances (HTTP)     │
+              │   :3001 → gbrain_zetit        │
+              │   :3002 → gbrain_telerapharma │
+              │   :3003 → gbrain_personal     │
+              │   :3004 → gbrain_community    │
+              └───────┬───────────────────────┘
+                      │
+              ┌───────┴───────────────────────┐
+              │  PostgreSQL 16 + pgvector     │
+              │  - brainhub (admin/auth/audit)│
+              │  - gbrain_zetit               │
+              │  - gbrain_telerapharma        │
+              │  - gbrain_personal            │
+              │  - gbrain_community           │
+              └───────────────────────────────┘
+```
+
+## Стек
+
+- **Backend**: Node.js 22 LTS + TypeScript + Express
+- **Frontend**: React 18 + TypeScript + Vite + Tailwind + shadcn/ui
+- **DB**: PostgreSQL 16 + pgvector + pg_trgm
+- **Auth**: Local email/password + Yandex OAuth + GitHub OAuth (passport.js)
+- **Engine**: gbrain (vendored через git.zetit.ru/zuevav/gbrain-mirror)
+- **Runtime**: Docker Compose в prod, native dev на разработке
+- **Deploy**: VM Ubuntu 22.04 в сети ZETIT
+
+## Структура репозитория
+
+```
+ZBrain/
+├── apps/
+│   ├── api/                # Express + TS backend
+│   └── web/                # React + Vite frontend
+├── packages/
+│   ├── shared/             # общие типы и утилиты
+│   └── mcp-proxy/          # MCP-прокси (валидация токенов, rate limit, audit)
+├── deploy/
+│   ├── docker/             # Dockerfile'ы и docker-compose
+│   ├── systemd/            # unit-файлы для нативного деплоя
+│   ├── nginx/              # конфиги reverse proxy
+│   └── postgres/           # init scripts, tuning
+├── docs/
+│   ├── ARCHITECTURE.md     # детальная архитектура
+│   ├── DEPLOYMENT.md       # инструкция по деплою
+│   ├── SECURITY.md         # модель безопасности
+│   ├── API.md              # API reference
+│   ├── ROADMAP.md          # план по спринтам
+│   └── DECISIONS/          # ADR (Architecture Decision Records)
+├── scripts/
+│   ├── bootstrap-vm.sh     # первичная установка на чистой Ubuntu 22.04
+│   ├── create-brain.sh     # создание нового gbrain instance
+│   ├── backup.sh           # бэкап всех БД
+│   └── restore.sh          # восстановление
+└── README.md               # этот файл
+```
+
+## Быстрый старт
+
+### Развёртывание production VM
+
+См. [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md). Кратко:
+
+```bash
+# 1. Создать VM (4 vCPU / 8 GB RAM / 80 GB SSD / Ubuntu 22.04)
+# 2. Склонировать репо
+git clone git@git.zetit.ru:zuevav/ZBrain.git /opt/zbrain
+cd /opt/zbrain
+
+# 3. Запустить bootstrap (ставит Postgres, Node, Bun, gbrain, тюнит ОС)
+sudo bash scripts/bootstrap-vm.sh
+
+# 4. Создать первый брейн
+sudo bash scripts/create-brain.sh zetit "ZETIT MSP" 3001
+
+# 5. Сконфигурировать .env (см. .env.example)
+sudo nano /etc/zbrain/.env
+
+# 6. Запустить brainhub
+cd /opt/zbrain
+docker compose up -d
+```
+
+### Локальная разработка
+
+```bash
+# Зависимости
+bun install
+
+# Postgres в docker
+docker compose -f deploy/docker/docker-compose.dev.yml up -d
+
+# Миграции
+bun run db:migrate
+
+# Запуск API + Web
+bun run dev
+```
+
+API на http://localhost:3000, Web на http://localhost:5173.
+
+## Дорожная карта
+
+Подробности — в [docs/ROADMAP.md](docs/ROADMAP.md). Кратко по спринтам:
+
+- **S0** — Инфраструктура VM, Postgres, базовая gbrain установка
+- **S1** — Первый рабочий gbrain через `gbrain serve --http`
+- **S2** — Каркас brainhub + локальный auth + RBAC
+- **S3** — MCP-прокси + токены с scope
+- **S4** — CRUD брейнов + источники + sync
+- **S5** — Dashboard + Projects + Connect страница
+- **S6** — OAuth (Yandex + GitHub) + публичный контур
+- **S7** — Audit, 2FA, backup, метрики, hardening
+
+## Безопасность
+
+- Каждый gbrain instance имеет **отдельного Postgres-пользователя** и **отдельную БД**
+- MCP-токены имеют **scope** (`mcp:read:<brain>`, `mcp:write:<brain>`, `mcp:admin:<brain>`)
+- Все MCP-запросы проходят через **brainhub-proxy**, не напрямую к gbrain
+- Все действия пишутся в **audit log**
+- Публичный контур принимает **только** `/mcp/*` и `/oauth/*`
+
+Подробности — [docs/SECURITY.md](docs/SECURITY.md).
+
+## Лицензия
+
+Proprietary. © ZETIT, Зуев А.В.
+
+gbrain используется по лицензии MIT, см. [гigit.zetit.ru/zuevav/gbrain-mirror](https://git.zetit.ru/zuevav/gbrain-mirror).
@@ -0,0 +1,56 @@
+{
+  "name": "@zbrain/api",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "bun run --watch src/main.ts",
+    "build": "tsc",
+    "start": "node dist/main.js",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "db:migrate": "bun run src/db/migrate.ts",
+    "db:seed": "bun run src/db/seed.ts",
+    "db:studio": "drizzle-kit studio"
+  },
+  "dependencies": {
+    "@zbrain/shared": "workspace:*",
+    "@zbrain/mcp-proxy": "workspace:*",
+    "express": "^4.21.0",
+    "cookie-parser": "^1.4.6",
+    "cors": "^2.8.5",
+    "helmet": "^8.0.0",
+    "compression": "^1.7.4",
+    "express-rate-limit": "^7.4.0",
+    "passport": "^0.7.0",
+    "passport-local": "^1.0.0",
+    "passport-yandex": "^0.0.5",
+    "passport-github2": "^0.1.12",
+    "bcryptjs": "^2.4.3",
+    "jsonwebtoken": "^9.0.2",
+    "drizzle-orm": "^0.34.0",
+    "postgres": "^3.4.4",
+    "zod": "^3.23.8",
+    "pino": "^9.4.0",
+    "pino-http": "^10.3.0",
+    "otplib": "^12.0.1",
+    "qrcode": "^1.5.4",
+    "http-proxy-middleware": "^3.0.3"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/cookie-parser": "^1.4.7",
+    "@types/cors": "^2.8.17",
+    "@types/compression": "^1.7.5",
+    "@types/passport": "^1.0.16",
+    "@types/passport-local": "^1.0.38",
+    "@types/bcryptjs": "^2.4.6",
+    "@types/jsonwebtoken": "^9.0.7",
+    "@types/qrcode": "^1.5.5",
+    "drizzle-kit": "^0.26.0",
+    "vitest": "^2.1.0",
+    "tsx": "^4.19.0"
+  }
+}
@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "declaration": false,
+    "outDir": "dist",
+    "rootDir": "src",
+    "baseUrl": ".",
+    "paths": {
+      "@zbrain/shared": ["../../packages/shared/src/index.ts"],
+      "@zbrain/shared/*": ["../../packages/shared/src/*"],
+      "@zbrain/mcp-proxy": ["../../packages/mcp-proxy/src/index.ts"]
+    }
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}
@@ -0,0 +1,48 @@
+{
+  "name": "@zbrain/web",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts,.tsx",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@zbrain/shared": "workspace:*",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-router-dom": "^6.27.0",
+    "@tanstack/react-query": "^5.59.0",
+    "axios": "^1.7.7",
+    "zustand": "^5.0.0",
+    "react-hook-form": "^7.53.0",
+    "zod": "^3.23.8",
+    "@hookform/resolvers": "^3.9.0",
+    "tailwindcss": "^3.4.13",
+    "lucide-react": "^0.451.0",
+    "clsx": "^2.1.1",
+    "tailwind-merge": "^2.5.4",
+    "class-variance-authority": "^0.7.0",
+    "date-fns": "^4.1.0",
+    "recharts": "^2.13.0",
+    "qrcode.react": "^4.0.1",
+    "react-hot-toast": "^2.4.1"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.11",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.3.2",
+    "vite": "^5.4.8",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0",
+    "autoprefixer": "^10.4.20",
+    "postcss": "^8.4.47",
+    "eslint": "^9.12.0",
+    "eslint-plugin-react": "^7.37.1",
+    "eslint-plugin-react-hooks": "^5.0.0"
+  }
+}
@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"],
+      "@zbrain/shared": ["../../packages/shared/src/index.ts"],
+      "@zbrain/shared/*": ["../../packages/shared/src/*"]
+    }
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}
@@ -0,0 +1,50 @@
+# ZBrain Development Docker Compose
+#
+# Только Postgres - всё остальное запускается нативно через bun/node.
+#
+# Запуск:
+#   docker compose -f deploy/docker/docker-compose.dev.yml up -d
+#
+# Подключение:
+#   psql postgresql://zbrain:dev@localhost:5432/brainhub_dev
+
+version: "3.9"
+
+services:
+  postgres:
+    image: pgvector/pgvector:pg16
+    container_name: zbrain-postgres-dev
+    restart: unless-stopped
+
+    environment:
+      POSTGRES_USER: zbrain
+      POSTGRES_PASSWORD: dev
+      POSTGRES_DB: brainhub_dev
+
+    ports:
+      - "127.0.0.1:5432:5432"
+
+    volumes:
+      - postgres-dev-data:/var/lib/postgresql/data
+      - ./init-dev.sql:/docker-entrypoint-initdb.d/init.sql:ro
+
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U zbrain"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+  # Опционально - adminer для просмотра БД через браузер
+  adminer:
+    image: adminer:latest
+    container_name: zbrain-adminer-dev
+    restart: unless-stopped
+    ports:
+      - "127.0.0.1:8081:8080"
+    environment:
+      ADMINER_DEFAULT_SERVER: postgres
+      ADMINER_DESIGN: pepa-linha-dark
+
+volumes:
+  postgres-dev-data:
+    driver: local
@@ -0,0 +1,78 @@
+# ZBrain Production Docker Compose
+#
+# Запуск:
+#   docker compose -f deploy/docker/docker-compose.yml up -d
+#
+# Postgres работает на хосте (не в контейнере) - так проще делать
+# нативный pg_dump, тюнинг и обновления без даунтайма всех брейнов.
+# gbrain instances тоже работают через systemd на хосте.
+# В контейнерах - только brainhub (api + web) и nginx.
+
+version: "3.9"
+
+services:
+  # ============================================================
+  # Brainhub API (Node.js + Express)
+  # ============================================================
+  brainhub-api:
+    build:
+      context: ../..
+      dockerfile: deploy/docker/api.Dockerfile
+    image: zbrain/brainhub-api:latest
+    container_name: zbrain-api
+    restart: unless-stopped
+
+    # Postgres на хосте, поэтому используем host network для api
+    # ИЛИ - оставляем bridge и в DATABASE_URL пишем host.docker.internal
+    network_mode: host
+
+    env_file:
+      - /etc/zbrain/.env
+
+    environment:
+      NODE_ENV: production
+      LOG_FILE: /var/log/zbrain/brainhub.log
+
+    volumes:
+      - /var/log/zbrain:/var/log/zbrain
+      - /etc/zbrain:/etc/zbrain:ro
+
+    healthcheck:
+      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:3000/health"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 30s
+
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "5"
+
+  # ============================================================
+  # Brainhub Web (статика через nginx внутри контейнера)
+  # ============================================================
+  brainhub-web:
+    build:
+      context: ../..
+      dockerfile: deploy/docker/web.Dockerfile
+    image: zbrain/brainhub-web:latest
+    container_name: zbrain-web
+    restart: unless-stopped
+
+    ports:
+      - "127.0.0.1:8080:80"  # только localhost, внешний доступ через системный nginx
+
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "5"
+
+# ============================================================
+# Networks
+# ============================================================
+# brainhub-api использует host network для прямого доступа к Postgres
+# и к gbrain instances (localhost:3001-3099).
+# brainhub-web стоит на bridge с port forward на 127.0.0.1:8080.
@@ -0,0 +1,17 @@
+-- ZBrain Dev Postgres Init
+-- Создаёт расширения и тестовые БД для локальной разработки
+
+CREATE EXTENSION IF NOT EXISTS vector;
+CREATE EXTENSION IF NOT EXISTS pg_trgm;
+CREATE EXTENSION IF NOT EXISTS pgcrypto;
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+
+-- Тестовая БД для gbrain
+CREATE DATABASE gbrain_dev OWNER zbrain;
+\c gbrain_dev
+CREATE EXTENSION IF NOT EXISTS vector;
+CREATE EXTENSION IF NOT EXISTS pg_trgm;
+CREATE EXTENSION IF NOT EXISTS pgcrypto;
+
+\c brainhub_dev
+-- В brainhub_dev расширения уже созданы выше, миграции прокатятся через приложение
@@ -0,0 +1,189 @@
+# ZBrain Nginx Configuration
+# ===========================
+# Два server-блока:
+#   1. Внутренний (brain.zetit.local) - полный доступ к UI и API
+#   2. Публичный (brain.zetit.ru) - только /mcp/* и /oauth/*
+#
+# Положить в /etc/nginx/sites-available/zbrain
+# и сделать symlink в /etc/nginx/sites-enabled/
+
+# ============================================================
+# Upstream'ы
+# ============================================================
+upstream brainhub_api {
+    server 127.0.0.1:3000;
+    keepalive 32;
+}
+
+upstream brainhub_api_public {
+    server 127.0.0.1:3010;
+    keepalive 32;
+}
+
+upstream brainhub_web {
+    server 127.0.0.1:8080;
+    keepalive 32;
+}
+
+# Rate limiting для публичного MCP
+limit_req_zone $binary_remote_addr zone=mcp_public:10m rate=30r/s;
+limit_req_zone $http_authorization zone=mcp_token:10m rate=100r/s;
+
+# ============================================================
+# Внутренний контур: brain.zetit.local
+# ============================================================
+server {
+    listen 80;
+    listen [::]:80;
+    server_name brain.zetit.local;
+
+    # Внутри сети можно без HTTPS, либо self-signed cert
+    # Если нужен HTTPS - раскомментировать listen 443 ниже и убрать listen 80
+
+    access_log /var/log/nginx/zbrain-internal.access.log;
+    error_log /var/log/nginx/zbrain-internal.error.log;
+
+    client_max_body_size 50M;
+
+    # Web UI (статика)
+    location / {
+        proxy_pass http://brainhub_web;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    # API
+    location /api/ {
+        proxy_pass http://brainhub_api;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header Connection "";
+
+        # Таймауты для долгих операций (sync, import)
+        proxy_read_timeout 300s;
+        proxy_send_timeout 300s;
+    }
+
+    # SSE events
+    location /api/events {
+        proxy_pass http://brainhub_api;
+        proxy_http_version 1.1;
+        proxy_set_header Connection "";
+        proxy_buffering off;
+        proxy_cache off;
+        proxy_read_timeout 24h;
+
+        # SSE headers
+        chunked_transfer_encoding off;
+    }
+
+    # MCP - внутренний доступ (тоже с токенами, но без rate limit)
+    location /mcp/ {
+        proxy_pass http://brainhub_api;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header Authorization $http_authorization;
+
+        proxy_read_timeout 120s;
+        proxy_buffering off;
+    }
+}
+
+# ============================================================
+# Публичный контур: brain.zetit.ru
+# ============================================================
+server {
+    listen 80;
+    listen [::]:80;
+    server_name brain.zetit.ru;
+
+    # HTTP -> HTTPS redirect (кроме ACME challenge)
+    location /.well-known/acme-challenge/ {
+        root /var/www/certbot;
+    }
+
+    location / {
+        return 301 https://$host$request_uri;
+    }
+}
+
+server {
+    listen 443 ssl http2;
+    listen [::]:443 ssl http2;
+    server_name brain.zetit.ru;
+
+    # TLS
+    ssl_certificate /etc/letsencrypt/live/brain.zetit.ru/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/brain.zetit.ru/privkey.pem;
+    ssl_session_timeout 1d;
+    ssl_session_cache shared:MozSSL:10m;
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_prefer_server_ciphers off;
+    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
+
+    # HSTS
+    add_header Strict-Transport-Security "max-age=63072000" always;
+
+    # Security headers
+    add_header X-Content-Type-Options "nosniff" always;
+    add_header X-Frame-Options "DENY" always;
+    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+
+    access_log /var/log/nginx/zbrain-public.access.log;
+    error_log /var/log/nginx/zbrain-public.error.log;
+
+    client_max_body_size 10M;
+
+    # ВАЖНО: на публичном контуре доступны только /mcp/* и /oauth/*
+    # Никакого UI, API админки и т.д.
+
+    # MCP proxy с rate limiting
+    location /mcp/ {
+        # Лимит по IP - защита от подбора токенов
+        limit_req zone=mcp_public burst=60 nodelay;
+        # Лимит по токену - защита от взбесившегося скрипта
+        limit_req zone=mcp_token burst=200 nodelay;
+        limit_req_status 429;
+
+        proxy_pass http://brainhub_api_public;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header Authorization $http_authorization;
+
+        proxy_read_timeout 120s;
+        proxy_buffering off;
+    }
+
+    # OAuth flow для удалённой авторизации
+    location /oauth/ {
+        limit_req zone=mcp_public burst=20 nodelay;
+
+        proxy_pass http://brainhub_api_public;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    # Health check (без rate limit, для мониторинга)
+    location /health {
+        proxy_pass http://brainhub_api_public/health;
+        access_log off;
+    }
+
+    # Всё остальное - 404, чтобы публично ничего лишнего не светить
+    location / {
+        return 404;
+    }
+}
@@ -0,0 +1,211 @@
+# Архитектура ZBrain
+
+## Обзор
+
+ZBrain — трёхслойная система:
+
+1. **gbrain** (vendored) — движок: хранилище, эмбеддинги, гибридный поиск, MCP server
+2. **brainhub** (наш код) — админка, прокси, auth, RBAC, audit
+3. **PostgreSQL** — единая СУБД с изоляцией по БД на каждый брейн
+
+## Принципы
+
+**Изоляция данных.** Каждый брейн (zetit, telerapharma, personal, community) живёт в отдельной БД с отдельным Postgres-пользователем. Утечка токена с правами на personal не даёт доступа к telerapharma на уровне СУБД.
+
+**Brainhub как единая точка входа.** Никакой Claude Code никогда не подключается к gbrain напрямую. Все MCP-запросы проходят через brainhub-proxy для аудита, rate limiting, проверки scope.
+
+**Vendored gbrain.** Зависимость от upstream'а закреплена в нашем git mirror'е с конкретным тегом. Обновления gbrain — управляемое решение, а не автоматический breaking change.
+
+**Two-zone deployment.** Внутренний контур (VPN, plain HTTP) для полного UI и админ-API; публичный контур (HTTPS + OAuth) только для `/mcp/*` и `/oauth/*`.
+
+## Компонентная диаграмма
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                          Clients                                │
+├─────────────────────────────────────────────────────────────────┤
+│  Claude Code (dev)    Claude Code (prod)    Cursor    Browser   │
+│       │                    │                  │         │       │
+└───────┼────────────────────┼──────────────────┼─────────┼───────┘
+        │                    │                  │         │
+   internal               public via         internal  internal
+   MCP                    nginx              MCP       HTTPS
+        │                    │                  │         │
+        ▼                    ▼                  ▼         ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                       Brainhub Process                          │
+│  ┌─────────────────────┐  ┌────────────────────────────────────┐│
+│  │ Internal Server     │  │ Public Server                      ││
+│  │ :3000               │  │ :3010                              ││
+│  │  - /api/*           │  │  - /mcp/* (с auth)                 ││
+│  │  - /mcp/* (с auth)  │  │  - /oauth/*                        ││
+│  │  - /api/events SSE  │  │                                    ││
+│  └──────────┬──────────┘  └──────────────┬─────────────────────┘│
+│             │                            │                      │
+│             └────────┬───────────────────┘                      │
+│                      │                                          │
+│   ┌──────────────────┴──────────────────┐                       │
+│   │  Shared modules                     │                       │
+│   │   - Auth service (passport.js)      │                       │
+│   │   - MCP Proxy + Token validator     │                       │
+│   │   - RBAC middleware                 │                       │
+│   │   - Audit logger                    │                       │
+│   │   - SSE event bus                   │                       │
+│   │   - Sync worker queue               │                       │
+│   └──────────────────┬──────────────────┘                       │
+│                      │                                          │
+└──────────────────────┼──────────────────────────────────────────┘
+                       │
+        ┌──────────────┴────────────┬─────────────┐
+        │                           │             │
+        ▼                           ▼             ▼
+┌───────────────┐        ┌────────────────┐   ┌──────────────┐
+│  Postgres     │        │  gbrain inst.  │   │  CLI (exec)  │
+│  brainhub DB  │        │  HTTP MCP      │   │              │
+│  - users      │        │  127.0.0.1:    │   │  gbrain      │
+│  - sessions   │        │   3001..3099   │   │   init       │
+│  - tokens     │        │                │   │   import     │
+│  - brains     │        │  21 MCP tools  │   │   sync       │
+│  - sources    │        │                │   │              │
+│  - projects   │        └────────┬───────┘   └──────┬───────┘
+│  - audit_log  │                 │                  │
+└───────────────┘                 ▼                  ▼
+                          ┌─────────────────────────────────┐
+                          │  Postgres (per-brain DBs)       │
+                          │  - gbrain_zetit                 │
+                          │  - gbrain_telerapharma          │
+                          │  - gbrain_personal              │
+                          │  - gbrain_community             │
+                          │                                 │
+                          │  Каждая со своим owner-user'ом  │
+                          └─────────────────────────────────┘
+```
+
+## Flow: MCP-запрос от Claude Code
+
+Допустим, Claude Code на сервере клиента делает search-запрос:
+
+```
+1. Claude Code:
+   POST https://brain.zetit.ru/mcp/zetit
+   Authorization: Bearer brain_pat_a8f3b2c1...
+   Content-Type: application/json
+   Body: {"jsonrpc":"2.0", "method":"tools/call", "params":{"name":"query","arguments":{"query":"how to renew sstp cert"}}}
+
+2. Nginx (brain.zetit.ru):
+   - rate_limit per IP (30 r/s) и per token (100 r/s)
+   - проксирует на 127.0.0.1:3010
+
+3. Brainhub public server:
+   - MCPProxy.middleware валидирует токен
+   - извлекает token из Bearer, считает SHA-256
+   - смотрит в кэш (in-memory, TTL 30s)
+     - если нет в кэше: SELECT FROM access_tokens WHERE token_hash = ?
+     - проверки: revoked_at IS NULL, expires_at > now(), IP в allowlist
+   - проверяет scope: содержит ли scopes[] 'mcp:read:zetit' или 'mcp:write:zetit'
+   - резолвит брейн: SELECT mcp_internal_port FROM brains WHERE name = 'zetit'
+   - пишет в audit_log queue: {action: 'mcp.call', resource: 'zetit', token_id: ..., method: 'query'}
+   - throttled update: token.last_used_at = now() (не чаще раза в минуту)
+   - проксирует на http://127.0.0.1:3001/mcp
+
+4. gbrain (zetit instance):
+   - выполняет hybrid search
+   - возвращает результаты
+
+5. Brainhub возвращает Claude Code stream of bytes как есть
+```
+
+**Времена:**
+- Без кэша: ~3-5ms (DB lookup) + gbrain латенси
+- С кэшем: ~0.5ms (cache hit) + gbrain латенси
+- Audit batch insert: раз в секунду, async, не влияет на латенси
+
+## Структура процесса brainhub
+
+Один Node.js процесс с двумя Express apps на разных портах:
+
+```typescript
+// apps/api/src/main.ts
+const internalApp = createInternalApp(); // /api, /mcp (с auth), UI proxy
+const publicApp = createPublicApp();      // /mcp, /oauth, /health
+
+internalApp.listen(3000, '127.0.0.1');    // только localhost
+publicApp.listen(3010, '127.0.0.1');      // только localhost
+```
+
+Nginx разруливает между ними по hostname:
+- `brain.zetit.local` → 127.0.0.1:3000
+- `brain.zetit.ru` → 127.0.0.1:3010
+
+Это даёт shared codebase, но чёткое разделение endpoints. Невозможно случайно выставить admin API в публичный контур.
+
+## Sync worker
+
+Sync — долгая операция (минуты до часов для большого корпуса). Не делать в-process на Express запросе.
+
+```typescript
+// Используем BullMQ или нативный setInterval с in-memory очередью
+
+// API endpoint только ставит задачу в очередь
+POST /api/brains/zetit/sources/git-1/sync
+  → syncQueue.add('sync', {brainId, sourceId})
+  → return {jobId}
+
+// Worker (отдельный процесс или setInterval):
+syncQueue.process('sync', async (job) => {
+  const {brainId, sourceId} = job.data;
+  const source = await db.sources.findById(sourceId);
+
+  // git pull
+  await exec(`cd ${source.config.local_path} && git pull`);
+
+  // запуск gbrain через CLI
+  const process = spawn('gbrain', ['sync', '--source', source.config.local_path], {
+    env: {...process.env, DATABASE_URL: brain.database_url}
+  });
+
+  // streaming output через SSE
+  process.stdout.on('data', (chunk) => {
+    sseEventBus.publish(`brain:${brainId}:sync:${sourceId}`, chunk.toString());
+  });
+
+  // update source.last_sync_at
+});
+```
+
+Cron триггерится из того же worker по расписанию (`source.schedule = '0 */6 * * *'`).
+
+## Кэширование
+
+| Что | Где | TTL | Зачем |
+|-----|-----|-----|-------|
+| Token validation | Memory (LRU) | 30s | избежать DB hit на каждом MCP запросе |
+| Brain port resolution | Memory | 5min | редко меняется |
+| User session | Memory | 5min | избежать DB hit на каждом auth check |
+| OAuth state | Redis (опционально) | 10min | CSRF protection для OAuth flow |
+
+В первой версии всё in-memory. Если процесс будет масштабироваться горизонтально — выносим в Redis.
+
+## Failure modes и их обработка
+
+| Что ломается | Что происходит | Что делаем |
+|--------------|----------------|------------|
+| Postgres down | brainhub не отвечает | health check 503, alerts |
+| gbrain instance crash | конкретный брейн не отвечает | brainhub возвращает 502 на /mcp/<brain>, остальные работают |
+| OpenAI API down | sync падает, search работает (без re-embed) | retry с backoff в worker |
+| FNA proxy down | gbrain не может делать embed | sync queue ждёт, alerts |
+| Disk full | Postgres перестаёт писать | Prometheus alert заранее на 80% |
+| Token leaked | злоумышленник делает запросы | Revoke в UI → cache invalidate в течение 30s |
+
+## Что НЕ делаем в первой версии
+
+Сознательно откладываем, чтобы не утонуть:
+
+- Horizontal scaling brainhub (один процесс на одной VM достаточно для нашего масштаба)
+- Sharding по брейнам на разные хосты (всё в одном Postgres)
+- Многотенантность (только наши пользователи, не SaaS)
+- WebSockets (SSE достаточно для realtime UI)
+- Service mesh, k8s (overkill для одной VM)
+- Свой forked gbrain (используем upstream через mirror)
+
+Эти решения можно пересмотреть через 6-12 месяцев на реальных метриках.
@@ -0,0 +1,60 @@
+# ADR-0001: Vendored gbrain через git mirror
+
+**Дата:** 2026-05-20
+**Статус:** Принято
+
+## Контекст
+
+gbrain (https://github.com/garrytan/gbrain) — активно развивающийся проект:
+- 60+ коммитов за последние 2 месяца
+- v0.26 (текущая) ввела breaking change: переход с bearer tokens на OAuth 2.1
+- Public API субпакетов (`gbrain/operations`, `gbrain/pglite-engine`) меняется
+
+Дополнительные факторы:
+- GitHub аккаунт zuevav был ограничен в апреле 2026, доступ к публичным репозиториям через `bun install -g github:garrytan/gbrain` может неожиданно ломаться
+- ZBrain зависит от стабильности gbrain в production
+- При следующей блокировке аккаунта мы не сможем переустановить или обновить gbrain
+
+## Решение
+
+Не зависеть от GitHub в runtime/install path. Зеркалить gbrain в свой git:
+
+```bash
+# Однократно, на чистом ноуте с работающим GitHub доступом:
+git clone --mirror https://github.com/garrytan/gbrain.git
+cd gbrain.git
+git remote set-url --push origin git@git.zetit.ru:zuevav/gbrain-mirror.git
+git push --mirror
+```
+
+Bootstrap-скрипт клонит из git.zetit.ru:
+
+```bash
+GBRAIN_REPO="https://git.zetit.ru/zuevav/gbrain-mirror.git" \
+GBRAIN_VERSION="v0.26.5" \
+bash scripts/bootstrap-vm.sh
+```
+
+## Последствия
+
+### Плюсы
+- Независимость от GitHub доступности и блокировок аккаунтов
+- Управляемое обновление gbrain (через `git fetch upstream && review && push to mirror`)
+- Возможность hotfix'ов локально, если upstream сломан (как форк, но в общем git)
+- Защита от supply chain атак (мы видим diff перед обновлением)
+
+### Минусы
+- Нужно вручную обновлять mirror (раз в месяц-два)
+- Лишний шаг в setup
+- Расхождение с upstream если хотфикс не запушим обратно
+
+### Митигация
+- Раз в месяц: проверка upstream'а, review diff, push to mirror
+- Все наши изменения (если потребуются) — в отдельной ветке `zetit/*`, чтобы не мерджились с upstream
+- Tag'ируем версии в нашем mirror'е (`v0.26.5-zetit-1`, если есть наши патчи)
+
+## Альтернативы рассмотренные
+
+1. **Прямая зависимость от github:garrytan/gbrain** — отвергнуто из-за рисков блокировки и breaking changes
+2. **Свой fork на git.zetit.ru с активной разработкой** — overkill, мы не планируем существенно дорабатывать gbrain
+3. **npm-publish gbrain в свой private npm registry** — gbrain не публикуется в npm как пакет; нужен install via bun + workspace
@@ -0,0 +1,92 @@
+# ADR-0002: Two-zone deployment (внутренний + публичный контур)
+
+**Дата:** 2026-05-20
+**Статус:** Принято
+
+## Контекст
+
+ZBrain должен обслуживать:
+
+1. **Внутренних пользователей** — owner (Алексей) и будущая команда работают через VPN/локальную сеть ZETIT. Им нужен полный UI: дашборд, управление брейнами, токенами, источниками, аудит.
+
+2. **Внешних агентов** — Claude Code на серверах клиентов (TeleraPharma, Fontvielle, и т.д.), которым нужен MCP-доступ к чтению/записи брейнов. У этих серверов нет VPN-доступа к ZETIT.
+
+Простое решение "выставить всё на публичный домен с auth" имеет недостатки:
+- Любая уязвимость в админ-UI становится публично доступной
+- OAuth flow на админ-эндпоинтах усложняет admin интеграции (curl, скрипты)
+- Утечка session cookie с админ-привилегиями через CSRF/XSS критична
+
+## Решение
+
+Развести функционал по двум сетевым контурам с разными доменами:
+
+### Внутренний контур (brain.zetit.local)
+
+- Доступен **только** из сети ZETIT и через VPN
+- Plain HTTP допустим (доверенная сеть, нет MITM риска)
+- Endpoints: **всё** — `/`, `/api/*`, `/mcp/*`, `/api/events` (SSE)
+- Auth: session cookie через local login (email/password) или OAuth
+- Используется: для web-UI, админских скриптов, debug'а
+
+### Публичный контур (brain.zetit.ru)
+
+- Доступен из интернета через TLS
+- Endpoints: **только** `/mcp/*`, `/oauth/*`, `/health`
+- Auth: Bearer tokens (для MCP) или OAuth flow (для подключения нового клиента)
+- Любой другой path → 404 (без подсказок что вообще существует)
+- Rate limiting per IP и per token
+- Используется: для удалённого Claude Code/Cursor, для машинного доступа
+
+## Реализация
+
+Один Node.js процесс запускает два независимых Express app на разных портах:
+
+```typescript
+// apps/api/src/main.ts
+const internalApp = createInternalApp();  // полный набор routes
+const publicApp = createPublicApp();      // только /mcp и /oauth
+
+internalApp.listen(3000, '127.0.0.1');
+publicApp.listen(3010, '127.0.0.1');
+```
+
+Nginx разруливает по hostname:
+
+```nginx
+server {
+  server_name brain.zetit.local;
+  location / { proxy_pass http://127.0.0.1:3000; }
+}
+
+server {
+  server_name brain.zetit.ru;
+  listen 443 ssl;
+  location /mcp/  { proxy_pass http://127.0.0.1:3010; }
+  location /oauth/ { proxy_pass http://127.0.0.1:3010; }
+  location /      { return 404; }
+}
+```
+
+## Последствия
+
+### Плюсы
+- Атака на админ-UI требует VPN или физического доступа к сети
+- Невозможно случайно выставить админ-API в публичный контур (architectural enforcement)
+- Rate limit на публичном контуре более агрессивный, не мешает админам
+- Раздельные access логи nginx для security audit
+
+### Минусы
+- Сложнее тестировать: нужно эмулировать два контура локально
+- DNS: две A-записи на разных серверах (внутренний и edge)
+- Невозможно "быстро дать админский доступ" партнёру не давая VPN
+
+### Митигация для разработки
+- Локально оба app слушают `127.0.0.1` на разных портах, host header проверяется в middleware
+- `.env.development` имеет флаг `DISABLE_ZONE_CHECK=true` для упрощённого dev режима
+- Integration тесты гоняют оба контура
+
+## Альтернативы рассмотренные
+
+1. **Один контур с строгой ролевой моделью** — отвергнуто, ошибка в RBAC становится критичной уязвимостью
+2. **Два разных процесса/контейнера** — overkill для одной VM, осложняет shared state (token cache)
+3. **API Gateway (Kong/Traefik)** — лишняя сущность для проекта такого размера
@@ -0,0 +1,103 @@
+# ADR-0003: Изоляция брейнов через отдельные PostgreSQL БД
+
+**Дата:** 2026-05-20
+**Статус:** Принято
+
+## Контекст
+
+ZBrain хостит несколько брейнов с разным уровнем чувствительности данных:
+
+- **zetit** — внутренние процессы ZETIT, не публичные
+- **telerapharma** — корпоративная инфраструктура с NDA
+- **personal** — личные данные владельца
+- **community** — данные о Смоленской 10, дом-чат, ЖКХ
+
+Утечка MCP токена с правами на один брейн **не должна** давать доступ к другим брейнам.
+
+Варианты изоляции в Postgres (от слабой к сильной):
+
+1. **Одна БД, одна схема, отдельные таблицы с префиксами** — слабая изоляция, любой SQL injection даёт доступ ко всему
+2. **Одна БД, отдельные schema'ы (zetit.pages, telerapharma.pages)** — изоляция через `search_path`, но один Postgres user видит всё
+3. **Одна БД, отдельные пользователи с row-level security** — сложно, легко допустить ошибку в RLS политиках
+4. **Отдельные БД с отдельными пользователями** — изоляция на уровне СУБД
+
+## Решение
+
+Вариант 4: **отдельная БД + отдельный Postgres-пользователь на каждый брейн**.
+
+```
+PostgreSQL cluster
+├── brainhub (БД)
+│   └── владелец: brainhub
+│       └── таблицы: users, sessions, tokens, brains, sources, projects, audit_log
+│
+├── gbrain_zetit (БД)
+│   └── владелец: gbrain_zetit
+│       └── полная схема gbrain (pages, chunks, embeddings, links, ...)
+│
+├── gbrain_telerapharma (БД)
+│   └── владелец: gbrain_telerapharma
+│       └── ...
+│
+├── gbrain_personal (БД)
+│   └── владелец: gbrain_personal
+│       └── ...
+│
+└── gbrain_community (БД)
+    └── владелец: gbrain_community
+        └── ...
+```
+
+Каждый gbrain-instance подключается к Postgres под своим пользователем и **физически не видит** другие БД:
+
+```sql
+-- Под пользователем gbrain_zetit
+\l
+-- Покажет только gbrain_zetit (и template/postgres)
+
+\c gbrain_telerapharma
+-- ERROR: permission denied for database gbrain_telerapharma
+```
+
+Brainhub использует свою БД `brainhub` под пользователем `brainhub` (тоже не видит остальные).
+
+## Реализация
+
+В `scripts/create-brain.sh`:
+
+```sql
+CREATE USER gbrain_${BRAIN_NAME} WITH PASSWORD '${random_password}';
+CREATE DATABASE gbrain_${BRAIN_NAME} OWNER gbrain_${BRAIN_NAME};
+GRANT ALL PRIVILEGES ON DATABASE gbrain_${BRAIN_NAME} TO gbrain_${BRAIN_NAME};
+-- НЕ выдаём этому юзеру ничего на other databases
+```
+
+Пароль для каждого gbrain-юзера генерируется случайно и хранится:
+1. В `/var/lib/zbrain/brains/<name>/config.json` (chmod 600, owner zbrain)
+2. В DATABASE_URL внутри systemd unit (Environment="DATABASE_URL=...")
+
+`brainhub` НЕ хранит эти пароли в своей БД (они не нужны для admin-операций) — только знает на каком порту слушает gbrain instance.
+
+## Последствия
+
+### Плюсы
+- Физическая изоляция через ACL Postgres
+- SQL injection в одном брейне не даёт доступ к другим
+- pg_dump каждого брейна тривиально по отдельности
+- Удаление брейна = одна команда `DROP DATABASE gbrain_X`
+- Разные параметры тюнинга на разные брейны (если потребуется)
+
+### Минусы
+- Нельзя сделать JOIN между брейнами в SQL (но это и не нужно — поиск через brainhub)
+- Каждая БД имеет свои индексы, общая нагрузка на shared_buffers Postgres делится
+- Backup делает дамп каждой БД отдельно (несложно)
+
+### Митигация
+- shared_buffers задан с запасом (2GB на 8GB RAM)
+- HNSW индексы строятся в `maintenance_work_mem=512MB`, одного брейна за раз достаточно
+
+## Альтернативы рассмотренные
+
+1. **Row-level security в одной БД** — сложно, требует консистентного применения политик на каждой таблице gbrain (а у gbrain их десятки). Один пропущенный CREATE POLICY = утечка
+2. **Отдельные Postgres-кластеры на каждый брейн** — overkill, 4× процессов, 4× shared_buffers
+3. **Отдельные VM на каждый брейн** — экстремальная изоляция, не нужна на нашем масштабе
@@ -0,0 +1,362 @@
+# Deployment Guide
+
+Полная инструкция по развёртыванию ZBrain с нуля.
+
+## Стадия 1: Подготовка VM
+
+### Спецификация
+
+| Параметр | Значение |
+|----------|----------|
+| ОС | Ubuntu 22.04 LTS Server |
+| CPU | 4 vCPU (минимум 2) |
+| RAM | 8 GB (минимум 4) |
+| Disk | 80 GB SSD (минимум 40) |
+| FS | ext4 |
+| Network | статический IP в сети ZETIT |
+
+### Создание
+
+1. На гипервизоре создать VM с указанными параметрами
+2. Установить Ubuntu 22.04 LTS Server (minimal)
+3. Создать пользователя `admin` с sudo правами
+4. Скопировать SSH-ключи: `ssh-copy-id admin@<ip>`
+5. Отключить password auth: `sudo passwd -l root` и в `/etc/ssh/sshd_config` `PasswordAuthentication no`
+
+### Базовая конфигурация
+
+```bash
+# Hostname
+sudo hostnamectl set-hostname zbrain
+echo "127.0.1.1 zbrain.zetit.local zbrain" | sudo tee -a /etc/hosts
+
+# Часовой пояс
+sudo timedatectl set-timezone Europe/Moscow
+
+# Обновления
+sudo apt-get update && sudo apt-get upgrade -y
+sudo apt-get install -y unattended-upgrades
+```
+
+### DNS
+
+В твоей внутренней DNS зоне (zetit.local или эквивалент):
+
+```
+brain.zetit.local.    A    <internal-ip>
+```
+
+На внешнем DNS (если используешь публичный контур):
+
+```
+brain.zetit.ru.    A    <external-ip-of-edge-server>
+```
+
+Edge-сервер (где живёт nginx с публичным контуром) проксирует на внутренний IP VM.
+
+## Стадия 2: Bootstrap
+
+```bash
+# Склонируй ZBrain repo
+sudo mkdir -p /opt/zbrain && sudo chown $USER:$USER /opt/zbrain
+git clone git@git.zetit.ru:zuevav/ZBrain.git /opt/zbrain
+cd /opt/zbrain
+
+# Зеркало gbrain (один раз, не на каждой VM)
+# Это делается единожды на твоей рабочей машине:
+#
+#   git clone --mirror https://github.com/garrytan/gbrain.git
+#   cd gbrain.git
+#   git push --mirror git@git.zetit.ru:zuevav/gbrain-mirror.git
+
+# Запусти bootstrap
+sudo TOTAL_RAM_GB=8 FNA_PROXY="http://client_001:PASSWORD@fna.zetit.ru:3128" bash scripts/bootstrap-vm.sh
+```
+
+После завершения скрипт покажет следующие шаги.
+
+## Стадия 3: Postgres secrets
+
+```bash
+sudo -u postgres psql
+```
+
+```sql
+-- Пароль root postgres юзера (сохрани в KeePass)
+ALTER USER postgres PASSWORD 'STRONG_RANDOM_PASSWORD_24_CHARS';
+
+-- Пользователь для brainhub
+CREATE USER brainhub WITH PASSWORD 'ANOTHER_STRONG_PASSWORD';
+GRANT ALL PRIVILEGES ON DATABASE brainhub TO brainhub;
+
+-- Проверка
+\du
+\l
+
+\q
+```
+
+## Стадия 4: Заполнение .env
+
+```bash
+sudo cp /etc/zbrain/env.example /etc/zbrain/.env
+sudo chmod 600 /etc/zbrain/.env
+sudo chown zbrain:zbrain /etc/zbrain/.env
+sudo nano /etc/zbrain/.env
+```
+
+Сгенерируй секреты:
+
+```bash
+# SESSION_SECRET
+openssl rand -hex 32
+
+# JWT_SECRET
+openssl rand -hex 32
+
+# TOKEN_ENCRYPTION_KEY (для шифрования TOTP секретов)
+openssl rand -hex 16
+```
+
+Заполни:
+- `DATABASE_URL` — с паролем brainhub
+- Секреты выше
+- `OPENAI_API_KEY` и `ANTHROPIC_API_KEY`
+- FNA-прокси с реальными credentials
+- `INITIAL_OWNER_EMAIL` и `INITIAL_OWNER_PASSWORD` (временный, сменишь после первого логина)
+
+## Стадия 5: Первый брейн
+
+```bash
+sudo bash /opt/zbrain/scripts/create-brain.sh zetit "ZETIT MSP" 3001
+```
+
+Скрипт:
+1. Создаст пользователя `gbrain_zetit` и БД `gbrain_zetit` в Postgres
+2. Положит конфиг в `/var/lib/zbrain/brains/zetit/`
+3. Запустит миграции gbrain
+4. Создаст и запустит systemd unit `zbrain-gbrain-zetit`
+
+Проверка:
+
+```bash
+systemctl status zbrain-gbrain-zetit
+journalctl -u zbrain-gbrain-zetit -f  # в отдельном окне
+curl http://localhost:3001/health
+```
+
+## Стадия 6: Импорт первых данных
+
+```bash
+sudo -u zbrain bash -c '
+  export PATH=$HOME/.bun/bin:$PATH
+  source /etc/zbrain/.env
+  cd /var/lib/zbrain/gbrain
+  bun run gbrain import /path/to/your/markdown/files
+'
+```
+
+Проверка:
+
+```bash
+sudo -u postgres psql -d gbrain_zetit -c '
+  SELECT
+    (SELECT count(*) FROM pages) AS pages,
+    (SELECT count(*) FROM content_chunks) AS chunks,
+    (SELECT count(*) FROM content_chunks WHERE embedding IS NOT NULL) AS embedded;
+'
+```
+
+## Стадия 7: Brainhub API + Web
+
+> Эта часть требует, чтобы код Sprint 2-5 был написан. До этого пропускаем.
+
+### Build
+
+```bash
+cd /opt/zbrain
+sudo -u zbrain bun install
+sudo -u zbrain bun run build
+```
+
+### Миграции
+
+```bash
+sudo -u zbrain bun run --cwd apps/api db:migrate
+```
+
+### Запуск через docker-compose (рекомендуется в prod)
+
+```bash
+cd /opt/zbrain/deploy/docker
+sudo docker compose up -d
+sudo docker compose ps
+```
+
+### Альтернатива: systemd
+
+Если не хочешь docker - использовать `deploy/systemd/zbrain-brainhub.service`.
+
+## Стадия 8: Nginx (внутренний контур)
+
+```bash
+sudo apt-get install -y nginx
+
+# Скопируй конфиг
+sudo cp /opt/zbrain/deploy/nginx/zbrain.conf /etc/nginx/sites-available/zbrain
+
+# Закомментируй временно public server-блок (TLS пока нет)
+
+sudo ln -s /etc/nginx/sites-available/zbrain /etc/nginx/sites-enabled/
+sudo rm /etc/nginx/sites-enabled/default
+
+# Проверь
+sudo nginx -t
+
+# Запусти
+sudo systemctl reload nginx
+```
+
+Тест:
+
+```bash
+curl -H "Host: brain.zetit.local" http://localhost/
+```
+
+## Стадия 9: TLS для публичного контура
+
+> Только если у тебя есть edge-сервер с внешним IP и DNS-запись brain.zetit.ru указывает на него.
+
+На edge-сервере (или на самой VM, если она имеет внешний IP):
+
+```bash
+sudo apt-get install -y certbot python3-certbot-nginx
+sudo certbot --nginx -d brain.zetit.ru
+```
+
+Раскомментируй public server-блок в nginx и перезагрузи.
+
+## Стадия 10: Первый логин
+
+1. Открой http://brain.zetit.local в браузере
+2. Залогинься как `INITIAL_OWNER_EMAIL` / `INITIAL_OWNER_PASSWORD`
+3. **Сразу смени пароль** в Profile
+4. Включи 2FA (когда Sprint 7 готов)
+5. Удали `INITIAL_OWNER_*` из `.env` (необязательно, но гигиенично)
+
+## Стадия 11: Подключение Claude Code
+
+1. В UI: создай токен с scope `mcp:write:zetit`
+2. Скопируй токен
+3. На своей рабочей машине добавь в `~/.claude/mcp.json` или в `.claude/mcp.json` проекта:
+
+```json
+{
+  "mcpServers": {
+    "zbrain-zetit": {
+      "transport": "http",
+      "url": "http://brain.zetit.local/mcp/zetit",
+      "headers": {
+        "Authorization": "Bearer brain_pat_<your-token>"
+      }
+    }
+  }
+}
+```
+
+4. Перезапусти Claude Code
+5. Проверь что MCP-инструменты доступны
+
+## Стадия 12: Backup
+
+```bash
+# Создай age ключ для шифрования бэкапов (только один раз!)
+age-keygen -o /tmp/backup.age
+cat /tmp/backup.age   # сохрани оба ключа в KeePass!
+
+# Положи публичную часть на VM
+sudo head -1 /tmp/backup.age | grep public | awk '{print $NF}' > /tmp/pub
+sudo mv /tmp/pub /etc/zbrain/backup.age.pub
+sudo chmod 644 /etc/zbrain/backup.age.pub
+
+# Удали /tmp/backup.age с VM!
+shred -u /tmp/backup.age
+
+# Тест бэкапа
+sudo bash /opt/zbrain/scripts/backup.sh
+
+# Добавь в cron
+sudo crontab -e
+# Добавь строку:
+# 0 3 * * *  /opt/zbrain/scripts/backup.sh >> /var/log/zbrain/backup.log 2>&1
+```
+
+## Чек-лист готовности
+
+- [ ] VM создана с правильными параметрами
+- [ ] Bootstrap отработал без ошибок
+- [ ] Postgres работает, пароли установлены
+- [ ] `.env` заполнен и защищён 600
+- [ ] Первый брейн создан и работает
+- [ ] Данные импортированы
+- [ ] Brainhub запущен и доступен через nginx
+- [ ] OAuth настроен (если нужно)
+- [ ] TLS работает (если публичный контур)
+- [ ] Owner логин работает, пароль сменён
+- [ ] Claude Code успешно подключается через токен
+- [ ] Backup делается и шифруется
+- [ ] Восстановление из бэкапа протестировано (на отдельной VM)
+- [ ] Мониторинг настроен (опционально)
+- [ ] Документация в `docs/INFRASTRUCTURE.md` обновлена
+
+## Типовые проблемы
+
+### gbrain не стартует
+
+```bash
+journalctl -u zbrain-gbrain-zetit -n 50 --no-pager
+```
+
+Частые причины:
+- Пароль в DATABASE_URL не совпадает
+- FNA-прокси недоступен
+- Bun не в PATH (проверь Environment="PATH=..." в unit-файле)
+
+### Embeddings не создаются
+
+```bash
+# Проверь подключение к OpenAI через FNA
+sudo -u zbrain bash -c '
+  source /etc/zbrain/.env
+  curl --proxy "$HTTPS_PROXY" https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY"
+'
+```
+
+### Postgres падает
+
+```bash
+# Проверь логи
+sudo tail -100 /var/log/postgresql/postgresql-16-main.log
+
+# Проверь disk space
+df -h /var/lib/postgresql/
+
+# Проверь shared_buffers vs RAM
+sudo -u postgres psql -c 'SHOW shared_buffers; SHOW effective_cache_size;'
+```
+
+### Брейн занимает слишком много места
+
+```bash
+# Размер по таблицам
+sudo -u postgres psql -d gbrain_zetit -c "
+SELECT
+  schemaname || '.' || tablename AS table,
+  pg_size_pretty(pg_total_relation_size(schemaname || '.' || tablename)) AS size
+FROM pg_tables
+WHERE schemaname = 'public'
+ORDER BY pg_total_relation_size(schemaname || '.' || tablename) DESC;
+"
+```
+
+Если эмбеддинги занимают слишком много — можно перейти на `text-embedding-3-small` (вместо `large`), это даст 1536 → 1024 dim и -33% места.
@@ -0,0 +1,319 @@
+# Operations Guide
+
+Документ для оператора ZBrain (admin) — повседневные задачи, типовые проблемы, runbook.
+
+## Чек-лист после деплоя
+
+После завершения [DEPLOYMENT.md](DEPLOYMENT.md):
+
+- [ ] Все systemd unit'ы для брейнов активны: `systemctl status 'zbrain-gbrain-*'`
+- [ ] Docker контейнеры brainhub запущены: `docker compose -f /opt/zbrain/deploy/docker/docker-compose.yml ps`
+- [ ] Nginx обслуживает оба домена: `curl -H "Host: brain.zetit.local" http://localhost/health`
+- [ ] Cron для backup'ов настроен: `sudo crontab -l | grep backup`
+- [ ] Логи пишутся: `ls -lh /var/log/zbrain/`
+- [ ] Disk usage в норме: `df -h /var/lib/postgresql /var/lib/zbrain /var/log`
+
+## Ежедневные задачи (автоматические)
+
+### Backup (cron, 03:00)
+
+```cron
+0 3 * * *  root  /opt/zbrain/scripts/backup.sh
+```
+
+Что проверять раз в неделю:
+- `ls -lh /var/backups/zbrain/` — есть свежий бэкап
+- `cat /var/log/zbrain/backup.log | tail -20` — нет ошибок
+- Раз в месяц — тестовое восстановление на отдельной VM
+
+### Sync (опционально, cron, 06:00 / 18:00)
+
+Если источники не настроены через UI с расписанием, можно запускать вручную через scripts/sync-all.sh (будет добавлено в Sprint 4).
+
+## Типовые задачи
+
+### Создать нового пользователя
+
+Через UI:
+1. Залогинься как owner
+2. /users → New user
+3. Email + role (admin / editor / viewer)
+4. Скопировать temp password из ответа
+
+Через CLI (только owner):
+```bash
+sudo docker exec zbrain-api node -e '
+  // TODO: команда будет добавлена в Sprint 7
+'
+```
+
+### Создать новый брейн
+
+```bash
+sudo bash /opt/zbrain/scripts/create-brain.sh <name> "<display name>" <port>
+
+# Пример
+sudo bash /opt/zbrain/scripts/create-brain.sh fontvielle "Fontvielle Infrastructure" 3005
+```
+
+### Импорт большого корпуса в брейн
+
+```bash
+sudo -u zbrain bash -c '
+  export PATH=$HOME/.bun/bin:$PATH
+  source /etc/zbrain/.env
+  export DATABASE_URL=$(cat /var/lib/zbrain/brains/zetit/config.json | jq -r .database_url)
+  cd /var/lib/zbrain/gbrain
+  bun run gbrain import /path/to/markdown/
+'
+```
+
+Для очень больших корпусов (>10000 страниц) — лучше через UI после Sprint 4, там SSE прогресс.
+
+### Обновить gbrain до новой версии
+
+1. **На рабочей машине** (с GitHub доступом):
+   ```bash
+   git clone --bare https://github.com/garrytan/gbrain.git
+   cd gbrain.git
+   git push --mirror git@git.zetit.ru:zuevav/gbrain-mirror.git
+   ```
+
+2. **На VM ZBrain** — проверить changelog upstream'а на breaking changes, особенно в БД схеме.
+
+3. Создать ADR в `docs/DECISIONS/` если есть значимые изменения.
+
+4. Останавливаем все брейны:
+   ```bash
+   sudo systemctl stop 'zbrain-gbrain-*'
+   ```
+
+5. Обновляем gbrain:
+   ```bash
+   sudo -u zbrain bash -c '
+     cd /var/lib/zbrain/gbrain
+     git fetch
+     git checkout v0.27.0   # новая версия
+     export PATH=$HOME/.bun/bin:$PATH
+     export HTTPS_PROXY=$(grep HTTPS_PROXY /etc/zbrain/.env | cut -d= -f2-)
+     bun install
+   '
+   ```
+
+6. Применяем миграции каждого брейна:
+   ```bash
+   for brain in zetit telerapharma personal community; do
+     sudo -u zbrain bash -c "
+       export PATH=\$HOME/.bun/bin:\$PATH
+       export DATABASE_URL=\$(cat /var/lib/zbrain/brains/$brain/config.json | jq -r .database_url)
+       cd /var/lib/zbrain/gbrain
+       bun run gbrain migrate
+     "
+   done
+   ```
+
+7. Запускаем брейны:
+   ```bash
+   sudo systemctl start 'zbrain-gbrain-*'
+   ```
+
+8. Проверяем health.
+
+### Восстановление из бэкапа
+
+См. `scripts/restore.sh`. Краткая инструкция:
+
+```bash
+sudo bash /opt/zbrain/scripts/restore.sh 20260520-031500
+# спросит путь к age приватному ключу
+```
+
+**ВАЖНО:** после restore удалить age ключ с VM:
+```bash
+shred -u /tmp/backup.age
+```
+
+### Реактивация заблокированного пользователя
+
+Если пользователь забыл пароль или нужно сбросить:
+
+```sql
+-- Через UI пока нет, делаем напрямую
+sudo -u postgres psql -d brainhub
+
+-- Сгенерировать новый bcrypt hash (cost=12)
+-- Можно через: echo 'newpassword' | htpasswd -bnBC 12 "" -
+UPDATE users
+SET password_hash = '<new-bcrypt-hash>',
+    must_change_password = true
+WHERE email = 'user@example.com';
+```
+
+### Срочный отзыв токена
+
+Если подозрение на утечку токена и нельзя ждать 30 секунд кэша:
+
+```bash
+# Через UI: /tokens → Revoke. Это уже делает invalidate cache.
+
+# Срочное через API:
+curl -X POST http://brain.zetit.local/api/admin/cache/invalidate-token \
+  -H "Authorization: Bearer <admin-session-token>" \
+  -H "Content-Type: application/json" \
+  -d '{"tokenPrefix":"brain_pat_a8f3"}'
+
+# Полный сброс кэша токенов (drastic):
+sudo systemctl restart docker
+sudo docker compose restart brainhub-api
+```
+
+## Мониторинг
+
+### Что смотреть в /var/log/zbrain/
+
+```bash
+# Live tail всех логов
+sudo tail -F /var/log/zbrain/*.log
+
+# Ошибки за последний час
+sudo journalctl --since "1 hour ago" -u 'zbrain-gbrain-*' | grep -i error
+
+# Brainhub access pattern
+sudo tail -1000 /var/log/zbrain/brainhub.log | jq -r 'select(.req.url) | "\(.time) \(.req.method) \(.req.url) → \(.res.statusCode)"'
+```
+
+### Метрики Postgres
+
+```bash
+# Connection count
+sudo -u postgres psql -c 'SELECT count(*), state FROM pg_stat_activity GROUP BY state;'
+
+# Размер БД
+sudo -u postgres psql -c "
+SELECT datname, pg_size_pretty(pg_database_size(datname))
+FROM pg_database WHERE datname IN ('brainhub','gbrain_zetit','gbrain_telerapharma','gbrain_personal','gbrain_community')
+ORDER BY pg_database_size(datname) DESC;
+"
+
+# Топ медленных запросов
+sudo -u postgres psql -c '
+SELECT calls, mean_exec_time, query
+FROM pg_stat_statements
+ORDER BY mean_exec_time DESC LIMIT 10;
+'  # если pg_stat_statements включён
+```
+
+### Disk usage
+
+```bash
+# По брейнам
+du -sh /var/lib/zbrain/brains/*/
+
+# Postgres data
+sudo du -sh /var/lib/postgresql/16/main/
+
+# Логи
+sudo du -sh /var/log/zbrain/ /var/log/postgresql/ /var/log/nginx/
+```
+
+Если /var/log пухнет — настроить logrotate.
+
+## Runbook'и инцидентов
+
+### Сценарий: брейн не отвечает на MCP запросы
+
+**Симптомы:** Claude Code получает 502 от /mcp/<brain>, в UI брейн помечен красным.
+
+```bash
+# 1. Проверить systemd unit
+sudo systemctl status zbrain-gbrain-<brain>
+
+# 2. Если down - последние логи
+sudo journalctl -u zbrain-gbrain-<brain> -n 100 --no-pager
+
+# 3. Если crash loop - проверить Postgres connection
+sudo -u postgres psql -d gbrain_<brain> -c 'SELECT version()'
+
+# 4. Если ОК - перезапустить
+sudo systemctl restart zbrain-gbrain-<brain>
+
+# 5. Если не помогло - временно отключить и эскалировать
+sudo systemctl stop zbrain-gbrain-<brain>
+```
+
+### Сценарий: Postgres недоступен
+
+**Симптомы:** brainhub возвращает 503, все брейны лежат.
+
+```bash
+# 1. Статус
+sudo systemctl status postgresql
+
+# 2. Если crashed - проверить логи
+sudo tail -200 /var/log/postgresql/postgresql-16-main.log
+
+# 3. Частые причины:
+#    a) Disk full → освободить место (старые WAL, логи)
+df -h /var/lib/postgresql
+sudo du -sh /var/lib/postgresql/16/main/pg_wal/
+
+#    b) OOM → проверить dmesg
+sudo dmesg | tail -50 | grep -i 'killed process'
+
+#    c) Corrupt → restore из бэкапа
+```
+
+### Сценарий: исчерпался лимит OpenAI/Anthropic API
+
+**Симптомы:** sync падает с 429, новые pages не получают embeddings.
+
+```bash
+# Проверка через FNA прокси
+sudo -u zbrain bash -c '
+  source /etc/zbrain/.env
+  curl --proxy "$HTTPS_PROXY" \
+       https://api.openai.com/v1/dashboard/billing/usage \
+       -H "Authorization: Bearer $OPENAI_API_KEY"
+'
+
+# Действия:
+# 1. Пополнить баланс на платформе OpenAI/Anthropic
+# 2. Или временно поставить на паузу автоматический sync
+# 3. Прикинуть стоимость re-embed: ~$0.65 на 7500 страниц для text-embedding-3-large
+```
+
+### Сценарий: подозрение на утечку токена
+
+```bash
+# 1. Найти токен в UI: /tokens → найти по prefix
+# 2. Посмотреть активность: /audit?actor_type=token&actor_id=<id>
+# 3. Revoke + invalidate cache
+# 4. Создать новый токен с теми же scope, передать пользователю
+# 5. Анализ через audit log:
+sudo -u postgres psql -d brainhub -c "
+SELECT created_at, ip, action, payload
+FROM audit_log
+WHERE actor_type='token' AND actor_id='<token-id>'
+ORDER BY created_at DESC LIMIT 100;
+"
+# 6. Если был доступ из неожиданного IP - эскалация (анализ что было прочитано/изменено)
+```
+
+## Регулярные процедуры
+
+### Раз в неделю
+- Проверить freshness бэкапов и логи backup.log
+- Проверить disk usage
+- Глянуть audit log на необычную активность
+
+### Раз в месяц
+- Тестовый restore на отдельной VM
+- Review обновлений gbrain upstream
+- Обновить ОС (`apt update && apt upgrade`)
+- Rotate session secrets (опционально, но повышает security posture)
+
+### Раз в квартал
+- Penetration test публичного контура (хотя бы на nikto/zap-baseline)
+- Review активных токенов, удаление неиспользуемых
+- Review активных пользователей, удаление неактивных
+- Capacity planning: смотреть рост БД и проектировать апгрейд VM при необходимости
@@ -0,0 +1,274 @@
+# ZBrain Roadmap
+
+Документ для Claude Code: пошаговый план реализации с критериями готовности каждого спринта. Подходит как для последовательной разработки, так и для параллельной (некоторые спринты независимы).
+
+## Принципы
+
+- Каждый спринт заканчивается **рабочей фичей**, которую можно показать
+- Каждый спринт мерж в `develop`, в `main` идут тегированные релизы
+- Любой Claude Code инстанс может прочитать этот файл и понять, что делать дальше
+- ADR (Architecture Decision Records) пишутся в `docs/DECISIONS/` для нестандартных решений
+
+---
+
+## Sprint 0: Инфраструктура VM (1 вечер)
+
+**Цель**: Готовая VM, на которой работает Postgres и установлен gbrain.
+
+**Задачи:**
+- [ ] Создать VM: 4 vCPU / 8 GB RAM / 80 GB SSD / Ubuntu 22.04 LTS
+- [ ] Назначить статический IP в сети ZETIT
+- [ ] Добавить DNS: `brain.zetit.local` (внутренний) и `brain.zetit.ru` (внешний)
+- [ ] Запустить `scripts/bootstrap-vm.sh`
+- [ ] Создать Postgres пользователя `brainhub` с паролем
+- [ ] Сгенерировать секреты для `.env` (SESSION_SECRET, JWT_SECRET, TOKEN_ENCRYPTION_KEY)
+- [ ] Получить API ключи: OPENAI_API_KEY, ANTHROPIC_API_KEY
+
+**Критерии готовности:**
+- `systemctl status postgresql` показывает active
+- `sudo -u postgres psql -d brainhub -c 'SELECT * FROM pg_extension'` возвращает vector, pg_trgm, pgcrypto
+- `sudo -u zbrain bash -c 'PATH=$HOME/.bun/bin:$PATH bun --version'` работает
+- `/etc/zbrain/.env` существует, заполнен, права 600
+
+**Документировать:** реальные параметры VM (IP, hostname, дата создания) в `docs/INFRASTRUCTURE.md`
+
+---
+
+## Sprint 1: Первый gbrain instance (1 день)
+
+**Цель**: Один работающий gbrain instance с импортированными тестовыми данными.
+
+**Задачи:**
+- [ ] Создать gbrain mirror в `git.zetit.ru/zuevav/gbrain-mirror`
+- [ ] Запустить `scripts/create-brain.sh zetit "ZETIT MSP" 3001`
+- [ ] Импортировать тестовый корпус (например, какие-то существующие markdown файлы)
+- [ ] Проверить `curl http://localhost:3001/health` или эквивалент
+- [ ] Прицепить локальный Claude Code напрямую к этому gbrain (без brainhub-прокси)
+- [ ] Выполнить пару query и убедиться что работает
+
+**Критерии готовности:**
+- `systemctl status zbrain-gbrain-zetit` показывает active
+- В БД есть страницы и эмбеддинги: `SELECT count(*) FROM pages, count(*) FROM content_chunks WHERE embedding IS NOT NULL`
+- Claude Code успешно делает MCP запросы
+
+**Известные риски:**
+- gbrain v0.26 переехал на новый OAuth - возможно поломались CLI флаги. Зафиксировать рабочую версию тегом.
+- FNA-прокси может блокировать какие-то OpenAI/Anthropic эндпоинты - проверить `curl --proxy ...` до запуска import.
+
+---
+
+## Sprint 2: Brainhub каркас + локальный auth (3-4 дня)
+
+**Цель**: Работающий веб-интерфейс с login/logout, без функционала брейнов.
+
+**Задачи:**
+
+### apps/api (backend)
+- [ ] Express + TypeScript скелет
+- [ ] Структура: `routes/`, `services/`, `middleware/`, `db/`, `lib/`
+- [ ] ORM выбрать: Drizzle (рекомендую за TS-first) или Prisma
+- [ ] Миграции: создать таблицы `users`, `sessions`
+- [ ] POST /api/auth/register (только для owner-команды, остальные через UI)
+- [ ] POST /api/auth/login (email + password, bcrypt)
+- [ ] POST /api/auth/logout
+- [ ] GET /api/auth/me (current user)
+- [ ] Session middleware (cookie + refresh token rotation)
+- [ ] RBAC middleware: `requireRole('admin')`, `requireRole('owner')`
+
+### apps/web (frontend)
+- [ ] React + Vite + TypeScript + Tailwind + shadcn/ui
+- [ ] Layout: sidebar + header + content
+- [ ] Страницы: /login, /dashboard (заглушка), /profile
+- [ ] React Router v6
+- [ ] React Query для API
+- [ ] Auth context + protected routes
+
+**Критерии готовности:**
+- На свежей БД создаётся initial owner из ENV (INITIAL_OWNER_EMAIL/PASSWORD)
+- Можно войти через UI на /login
+- /dashboard защищён, без auth редиректит на /login
+- Cookie с session token, при logout удаляется
+- Refresh token rotation работает (логин не истекает через 15 минут активной сессии)
+
+---
+
+## Sprint 3: MCP Proxy + Tokens (2-3 дня)
+
+**Цель**: Claude Code на любом сервере подключается через brainhub, а не напрямую к gbrain.
+
+**Задачи:**
+
+### packages/mcp-proxy
+- [ ] Express router, маунтится на `/mcp/:brain`
+- [ ] Извлечение Bearer token из заголовков
+- [ ] Кэш токенов в памяти (30s TTL) - не ходить в БД на каждый запрос
+- [ ] Проверка: revoked, expired, IP allowlist, scope
+- [ ] Резолв `:brain` → `localhost:PORT` через таблицу `brains`
+- [ ] Прокси через `http-proxy-middleware` или nativный stream
+- [ ] In-memory очередь для audit log + batch insert (раз в секунду)
+- [ ] Throttled update `last_used_at` (не чаще раза в минуту на токен)
+
+### apps/api: токены
+- [ ] Таблица `access_tokens` (см. docs/SECURITY.md)
+- [ ] POST /api/tokens (создание - возвращает plaintext token ОДИН РАЗ)
+- [ ] GET /api/tokens (список с prefix, без full token)
+- [ ] DELETE /api/tokens/:id (revoke - soft delete с revoked_at)
+- [ ] GET /api/tokens/:id/usage (статистика)
+
+### apps/web: UI для токенов
+- [ ] /tokens страница со списком
+- [ ] Создание токена: имя + scope checkboxes + TTL + IP allowlist
+- [ ] После создания - модалка с токеном и кнопкой copy (показывается один раз!)
+- [ ] Revoke с подтверждением
+
+**Критерии готовности:**
+- Создал токен в UI с scope `mcp:read:zetit`
+- Подключил Claude Code: `mcpServers.zbrain.url = http://brain.zetit.local/mcp/zetit`, header `Authorization: Bearer brain_pat_...`
+- Запрос идёт через brainhub, в audit log записывается
+- Revoke токена через UI → следующий запрос Claude Code получает 401
+- При двух токенах одного scope работают оба
+
+---
+
+## Sprint 4: CRUD брейнов + источники + sync (2-3 дня)
+
+**Цель**: Создание новых брейнов через UI, добавление и синхронизация источников.
+
+**Задачи:**
+
+### apps/api
+- [ ] Таблицы `brains`, `sources`
+- [ ] POST /api/brains - создание (внутренний вызов `scripts/create-brain.sh` или эквивалент на TS)
+- [ ] GET /api/brains - список со статистикой (page_count, embed_coverage)
+- [ ] GET /api/brains/:id - детали
+- [ ] DELETE /api/brains/:id - удаление (с подтверждением, дамп перед удалением)
+- [ ] POST /api/brains/:id/sources - добавление источника (git, local_dir)
+- [ ] POST /api/brains/:id/sources/:sourceId/sync - запуск sync
+- [ ] GET /api/brains/:id/sources/:sourceId/sync/stream - SSE с прогрессом
+- [ ] Worker queue для sync (bullmq или нативный setInterval)
+- [ ] Планировщик cron-based sync (node-cron)
+
+### apps/web
+- [ ] /brains страница со списком
+- [ ] /brains/new форма создания
+- [ ] /brains/:id - tabs: Overview, Sources, Browse, Query, Activity
+- [ ] Sources tab: список с status, кнопки Sync now / Edit / Delete
+- [ ] Sync с realtime прогрессом через SSE
+- [ ] Подсветка статусов: green/yellow/red
+
+**Критерии готовности:**
+- Создать брейн `community` через UI → автоматически создаётся БД, запускается gbrain, регистрируется systemd unit
+- Добавить git source → запустить sync → видеть прогресс в реальном времени
+- Расписание sync каждые 6 часов работает
+- Удаление брейна делает дамп и убирает все артефакты
+
+**Важно:** удаление брейна - irreversible операция, обязательно подтверждение через ввод имени брейна (как в GitHub).
+
+---
+
+## Sprint 5: Dashboard + Projects + Connect (2-3 дня)
+
+**Цель**: Полноценный UI с визуализацией проектов и copy-paste готовыми сниппетами.
+
+**Задачи:**
+
+### apps/api
+- [ ] Таблицы `projects`, `project_connections`
+- [ ] CRUD endpoints для projects
+- [ ] POST /api/projects/:id/connections - привязка проекта к брейну с указанием токена
+- [ ] GET /api/connect/snippets/:brainId?client=claude-code|cursor|cli - генерация сниппетов
+
+### apps/web
+- [ ] /dashboard - сводка: количество брейнов, total pages, active sync jobs, recent activity
+- [ ] /dashboard карточки брейнов с цифрами
+- [ ] /projects - таблица проектов с привязкой к брейнам
+- [ ] /projects/:id - детали + кнопка "Connect new brain"
+- [ ] /brains/:id/connect - страница с готовыми сниппетами:
+    - Claude Code JSON (для `~/.claude/mcp.json` или `.claude/mcp.json` в проекте)
+    - Cursor конфиг
+    - Bash one-liner для CLI
+    - QR код с готовой строкой подключения
+- [ ] Copy-to-clipboard на каждом блоке
+- [ ] Глобальный поиск по всем брейнам (с уважением scope)
+
+**Критерии готовности:**
+- Dashboard загружается за <500ms
+- В Projects вижу таблицу: ZetitConnect → [zetit (write), personal (read)]
+- На странице Connect - готовая JSON структура с реальным URL и токеном, копируется одним кликом
+- QR-код корректно сканируется и содержит JSON
+
+---
+
+## Sprint 6: OAuth + публичный контур (2-3 дня)
+
+**Цель**: Авторизация через Yandex/GitHub OAuth, публичный endpoint для MCP.
+
+**Задачи:**
+
+### apps/api
+- [ ] Зарегистрировать OAuth приложения у Yandex и GitHub
+- [ ] passport.js + passport-yandex + passport-github2
+- [ ] OAuth flow: /oauth/yandex, /oauth/yandex/callback (аналогично GitHub)
+- [ ] Привязка к existing user по email match (с подтверждением)
+- [ ] Поддержка регистрации нового пользователя через OAuth (опционально, по INVITE_ONLY флагу)
+- [ ] Отдельный Express app на 3010 порту, монтирует только /mcp и /oauth
+
+### deploy
+- [ ] Получить TLS сертификат от Let's Encrypt для brain.zetit.ru
+- [ ] Включить nginx public server-блок
+- [ ] Проверить, что внутренний и публичный API не пересекаются (нет утечки UI на публичный)
+
+**Критерии готовности:**
+- Залогиниться через "Sign in with Yandex" - работает
+- На публичном endpoint `https://brain.zetit.ru/api/brains` → 404
+- На публичном endpoint `https://brain.zetit.ru/mcp/zetit` → работает с токеном
+- TLS A+ rating на SSL Labs
+
+---
+
+## Sprint 7: Hardening (2-3 дня)
+
+**Цель**: Production-ready: бэкапы, мониторинг, 2FA, документация.
+
+**Задачи:**
+- [ ] /audit страница в UI с фильтрами (actor, action, resource, date range)
+- [ ] CSV export audit log
+- [ ] 2FA (TOTP) опционально для каждого пользователя
+- [ ] Проверить и настроить `scripts/backup.sh`, добавить в cron
+- [ ] Тестовое восстановление из бэкапа на отдельной VM
+- [ ] Prometheus endpoint /metrics: request rate, error rate, db connections, queue depth
+- [ ] Health endpoint с глубокой проверкой (DB connectivity, gbrain instances)
+- [ ] Alerts на падение sync, на error rate > N
+- [ ] Documentation: docs/API.md, docs/SECURITY.md, docs/OPERATIONS.md
+- [ ] Load test: 100 RPS на /mcp, что выдерживает
+
+**Критерии готовности:**
+- Восстановление из бэкапа прошло успешно
+- Включил 2FA на owner аккаунте, работает
+- /metrics возвращает prometheus formatted text
+- Audit log имеет все важные события: brain.create, brain.delete, token.create, token.revoke, user.login, user.logout, mcp.call
+
+---
+
+## После Sprint 7: миграция данных
+
+**Цель**: Перенести всё что нужно в соответствующие брейны.
+
+- [ ] Создать брейны: zetit, telerapharma, personal, community (если ещё не созданы)
+- [ ] Источники для zetit: ZetitConnect docs repo, ZETIT internal wiki
+- [ ] Источники для telerapharma: runbook'и Exchange/MikroTik/1C
+- [ ] Источники для personal: личный markdown garden, "Хлеб и молоко" docs
+- [ ] Источники для community: документы Смоленская 10
+- [ ] Переключить Claude Code на всех серверах с локального чтения на gbrain через brainhub
+- [ ] Удалить дублированную документацию из локальных копий (оставить только в источниках)
+
+---
+
+## Дальнейшее развитие
+
+- Импорт из Notion, Obsidian, Confluence через gbrain skills
+- Webhook'и: уведомления в Slack/Telegram при критичных событиях
+- API для интеграций с другими системами (1С, FortiGate logs)
+- Mobile-friendly UI (адаптив или отдельная PWA)
+- Multi-user collaboration на одном брейне (комментарии, suggestions)
+- Версионирование промптов и skills через gbrain
@@ -0,0 +1,357 @@
+# Безопасность ZBrain
+
+## Модель угроз
+
+**Что защищаем:**
+- Содержимое брейнов (особенно TeleraPharma — есть NDA и чувствительная инфраструктурная информация)
+- Учётные записи пользователей
+- API ключи (OpenAI, Anthropic) — финансовые потери при утечке
+- MCP токены — могут давать доступ к чтению/записи брейнов
+
+**От кого защищаем:**
+- **Внешний атакующий** через публичный endpoint brain.zetit.ru
+- **Скомпрометированный сервер клиента** с украденным MCP токеном
+- **Случайная утечка** через копирование токена в git, log файлы, скриншот
+- **Внутренний пользователь** с правами viewer, который хочет получить admin
+
+**От чего не защищаемся (нет ресурсов):**
+- Физический доступ к VM (предполагаем что гипервизор/датацентр доверенный)
+- Скомпрометированный root на самой VM
+- 0-day в Postgres, Node.js, библиотеках
+
+## Роли пользователей
+
+| Роль | Управление пользователями | Управление брейнами | Управление источниками | Управление токенами | Просмотр audit | UI |
+|------|---------------------------|---------------------|------------------------|--------------------|-----|---|
+| **owner** | ✓ Полное | ✓ Полное | ✓ Полное | ✓ Полное | ✓ Все | ✓ |
+| **admin** | Только viewer/editor | ✓ Полное | ✓ Полное | ✓ Свои + смотреть чужие | ✓ Все | ✓ |
+| **editor** | ✗ | ✗ Создавать нельзя; редактировать содержимое — да | ✓ В назначенных брейнах | ✓ Свои с scope :read и :write | ✓ Свои действия | ✓ |
+| **viewer** | ✗ | ✗ | ✗ | ✓ Свои только :read | ✓ Свои действия | ✓ Read-only |
+| **agent** (не человек) | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ MCP only |
+
+В первой версии у нас один owner — это ты. Остальные роли — для будущего.
+
+## MCP Токены
+
+### Формат
+
+```
+brain_pat_<random40chars>
+```
+
+Префикс `brain_pat_` (Personal Access Token) — чтобы легко grep'ать в логах и автоматических сканерах секретов.
+
+### Хранение
+
+- Plain text токен **никогда** не хранится
+- Хранится `token_hash = SHA-256(token)` и `token_prefix = первые 8 символов после brain_pat_` для UI
+- При создании токена UI показывает full token **один раз**, потом только prefix
+
+### Scope формат
+
+```
+mcp:<level>:<brain-name>
+```
+
+Уровни:
+- `mcp:read:<brain>` — query, search, get_page, get_tags, get_links, get_backlinks, get_timeline, get_stats, get_health, get_versions
+- `mcp:write:<brain>` — всё из read + put_page, add_tag, remove_tag, add_link, remove_link, add_timeline_entry, sync_brain
+- `mcp:admin:<brain>` — всё из write + delete_page, revert_version
+
+Wildcards:
+- `mcp:read:*` — read доступ ко всем брейнам (только owner)
+- `mcp:*:zetit` — все права на zetit брейн
+
+Один токен может иметь несколько scope, например:
+```json
+{
+  "scopes": ["mcp:read:zetit", "mcp:write:personal"]
+}
+```
+
+### IP Allowlist
+
+Опционально для каждого токена — список IP/CIDR откуда разрешён доступ.
+
+Для production токенов (на серверах клиентов) — **обязательно** указывать IP клиентского сервера.
+
+### TTL
+
+- По умолчанию: 90 дней
+- Опции в UI: 7 дней, 30 дней, 90 дней, 1 год, без срока
+- "Без срока" доступен только owner и admin
+
+### Revocation
+
+Soft delete: `revoked_at = now()`.
+
+Кэш в brainhub имеет TTL 30 секунд, поэтому отзыв вступает в силу в течение 30 секунд.
+
+Для немедленного отзыва — `POST /api/admin/cache/invalidate-token`.
+
+### Алгоритм валидации
+
+```typescript
+async function validateToken(token: string, brain: string, requiredScope: 'read'|'write'|'admin'): Promise<TokenInfo> {
+  // 1. Проверка формата
+  if (!token.startsWith('brain_pat_')) throw new Error('Invalid token format');
+
+  const tokenHash = sha256(token);
+
+  // 2. Проверка в кэше
+  const cached = tokenCache.get(tokenHash);
+  if (cached) {
+    if (cached.error) throw new Error(cached.error);
+    return validateScope(cached, brain, requiredScope);
+  }
+
+  // 3. DB lookup
+  const dbToken = await db.tokens.findByHash(tokenHash);
+  if (!dbToken) {
+    tokenCache.set(tokenHash, {error: 'Not found'}, 30_000);
+    throw new Error('Token not found');
+  }
+
+  // 4. Проверки статуса
+  if (dbToken.revoked_at) throw new Error('Token revoked');
+  if (dbToken.expires_at && dbToken.expires_at < new Date()) throw new Error('Token expired');
+
+  // 5. IP allowlist
+  if (dbToken.ip_allowlist?.length > 0) {
+    const clientIp = getClientIp();
+    if (!isIpInAllowlist(clientIp, dbToken.ip_allowlist)) {
+      throw new Error('IP not allowed');
+    }
+  }
+
+  // 6. Scope check
+  validateScope(dbToken, brain, requiredScope);
+
+  // 7. Кэшируем positive result
+  tokenCache.set(tokenHash, dbToken, 30_000);
+
+  // 8. Throttled last_used update
+  scheduleLastUsedUpdate(dbToken.id);
+
+  return dbToken;
+}
+```
+
+## Сессии
+
+### Cookie
+
+```
+Name: zbrain_session
+Value: <jwt-signed session id>
+HttpOnly: true
+Secure: true (только в production)
+SameSite: Lax
+Path: /
+Domain: brain.zetit.local или brain.zetit.ru
+```
+
+JWT внутри cookie - только session id, не данные пользователя. Все данные подтягиваются из БД по session id.
+
+### Refresh tokens
+
+- Access JWT: 15 минут
+- Refresh token: 30 дней, ротируется при каждом использовании
+- Refresh token хранится в БД как hash (см. таблицу `sessions`)
+
+### Logout
+
+- Удаление cookie
+- `sessions.revoked_at = now()` для всех сессий пользователя (если "logout everywhere")
+
+## OAuth
+
+### Поддерживаемые провайдеры
+
+1. **Yandex** (основной)
+2. **GitHub** (резервный)
+3. **Local email/password** (всегда доступен для owner)
+
+### Привязка к существующему пользователю
+
+Если OAuth возвращает email, который уже есть в users:
+- Если у пользователя нет привязки OAuth → требуется подтверждение пароля
+- Если есть привязка к другому провайдеру → ошибка ("Already linked to GitHub")
+- Если есть привязка к этому же провайдеру → login успешный
+
+### Новые пользователи через OAuth
+
+По умолчанию **отключено** (флаг `OAUTH_AUTO_REGISTER=false`).
+
+В первой версии — только invite-based: owner создаёт пользователя с email, тот логинится через OAuth, происходит match по email.
+
+## 2FA (TOTP)
+
+Опционально, в Sprint 7.
+
+- Секрет генерируется при включении, показывается QR-код для Google Authenticator / Authy
+- Сохраняется в `users.totp_secret` зашифрованным
+- 8 backup codes генерируются и показываются один раз
+- При логине после успешного password check → требуется TOTP код
+- Для OAuth-логина 2FA не запрашивается (полагаемся на 2FA провайдера)
+
+## Audit Log
+
+### Что пишем
+
+Категории событий:
+
+**Auth:**
+- `user.login.success` / `user.login.failure`
+- `user.logout`
+- `user.oauth.link` / `user.oauth.unlink`
+- `user.totp.enable` / `user.totp.disable`
+
+**User management:**
+- `user.create`
+- `user.update`
+- `user.delete`
+- `user.role.change`
+
+**Brain management:**
+- `brain.create`
+- `brain.update`
+- `brain.delete`
+- `brain.sync.start` / `brain.sync.complete` / `brain.sync.fail`
+
+**Source management:**
+- `source.add`
+- `source.update`
+- `source.delete`
+
+**Token management:**
+- `token.create` (с указанием scopes)
+- `token.revoke`
+
+**MCP usage:**
+- `mcp.call` (rate-sampled: 1 запись на 10 вызовов на токен в минуту)
+
+**Admin actions:**
+- `admin.cache.invalidate`
+- `admin.config.update`
+
+### Формат
+
+```typescript
+{
+  id: bigint,                        // serial
+  actor_type: 'user' | 'token',
+  actor_id: uuid,                    // user.id или token.id
+  action: string,                    // 'brain.create', 'mcp.call', etc.
+  resource_type: string?,            // 'brain', 'token', 'source', etc.
+  resource_id: string?,              // ID объекта
+  payload: jsonb,                    // дополнительные данные
+  ip: inet?,
+  user_agent: text?,
+  created_at: timestamptz
+}
+```
+
+### Хранение
+
+- Хранятся **навсегда** в первой версии (для compliance)
+- В будущем — архив старее года в отдельную холодную БД
+- Индексы: `(actor_type, actor_id, created_at DESC)`, `(resource_type, resource_id, created_at DESC)`
+
+### Batch insert
+
+MCP-запросов будет много (тысячи в день). Не делаем INSERT на каждый запрос:
+
+```typescript
+const auditQueue: AuditEntry[] = [];
+
+// API endpoint:
+function logAudit(entry: AuditEntry) {
+  auditQueue.push(entry);
+  // не ждём insert
+}
+
+// Worker раз в секунду:
+setInterval(async () => {
+  if (auditQueue.length === 0) return;
+  const batch = auditQueue.splice(0, 1000);
+  await db.audit_log.insertMany(batch);
+}, 1000);
+
+// graceful shutdown:
+process.on('SIGTERM', async () => {
+  if (auditQueue.length > 0) {
+    await db.audit_log.insertMany(auditQueue);
+  }
+});
+```
+
+## Сетевая безопасность
+
+### Внутренний контур (brain.zetit.local)
+
+- Доступ только из сети ZETIT или через VPN
+- Plain HTTP допустим (доверенная сеть)
+- Postgres слушает только localhost (127.0.0.1)
+- UFW: открыты только 22 (SSH), 80, 443
+
+### Публичный контур (brain.zetit.ru)
+
+- Только HTTPS, TLS 1.2+ с safe ciphers
+- Rate limiting на nginx уровне:
+  - 30 r/s per IP (защита от подбора токенов)
+  - 100 r/s per token (защита от runaway script)
+- Доступны только `/mcp/*`, `/oauth/*`, `/health`
+- Любой другой path → 404 без подсказок
+
+### SSH
+
+- Только ключи, password auth отключён
+- `PermitRootLogin no`
+- Fail2ban на /var/log/auth.log
+
+## Защита секретов
+
+### В коде
+
+- НИКОГДА не коммитим `.env`, `*.key`, `*.pem`
+- `.gitignore` строгий
+- Pre-commit hook с git-secrets или talisman (опционально)
+
+### На VM
+
+- `/etc/zbrain/.env` — права 600, owner zbrain
+- Postgres пароли каждого брейна — в `/var/lib/zbrain/brains/<name>/config.json` (600, owner zbrain)
+- API ключи OpenAI/Anthropic — в .env, не в коде
+- TLS приватные ключи в `/etc/letsencrypt/live/` — стандартные права Let's Encrypt
+
+### В БД
+
+- Пароли пользователей — bcrypt с cost=12
+- MCP токены — SHA-256 hash (HMAC не нужен, потому что коллизии не критичны)
+- TOTP secrets — AES-128-GCM с ключом из TOKEN_ENCRYPTION_KEY
+- OAuth subjects — открытым текстом (это не секрет)
+
+### Backup
+
+- Полный бэкап шифруется age (или GPG) перед сохранением
+- Публичный ключ для шифрования — на VM в /etc/zbrain/backup.age.pub
+- Приватный ключ для расшифровки — **НЕ на VM**, хранится отдельно (KeePass / safe / другая машина)
+
+## Чек-лист безопасности перед production
+
+- [ ] Все пароли Postgres сильные (≥24 символа, generated)
+- [ ] `/etc/zbrain/.env` с правами 600
+- [ ] UFW активен, открыты только нужные порты
+- [ ] Fail2ban настроен для SSH и nginx
+- [ ] TLS сертификат валиден (A+ rating на ssllabs.com)
+- [ ] Postgres listen_addresses = 'localhost'
+- [ ] Создан age ключ для бэкапов, приватная часть НЕ на этой VM
+- [ ] Скрипт backup.sh в cron, протестирован restore
+- [ ] OAuth приложения зарегистрированы, callback URL'ы правильные
+- [ ] Owner аккаунт создан, password сильный, 2FA включена (после Sprint 7)
+- [ ] INITIAL_OWNER_PASSWORD сменён после первого логина
+- [ ] Audit log пишется и читается через UI
+- [ ] Test: попытка доступа к /api/* через brain.zetit.ru → 404
+- [ ] Test: запрос с revoked токеном → 401 в течение 30 секунд
+- [ ] Test: запрос с неверным scope → 403
@@ -0,0 +1,37 @@
+{
+  "name": "zbrain",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Централизованная база знаний для AI-агентов ZETIT",
+  "repository": {
+    "type": "git",
+    "url": "git@git.zetit.ru:zuevav/ZBrain.git"
+  },
+  "author": "Зуев Алексей Викторович <zuev@zetit.ru>",
+  "license": "UNLICENSED",
+  "workspaces": [
+    "apps/*",
+    "packages/*"
+  ],
+  "scripts": {
+    "dev": "bun run --filter '*' dev",
+    "build": "bun run --filter '*' build",
+    "lint": "bun run --filter '*' lint",
+    "test": "bun run --filter '*' test",
+    "typecheck": "bun run --filter '*' typecheck",
+    "db:migrate": "bun run --cwd apps/api db:migrate",
+    "db:seed": "bun run --cwd apps/api db:seed",
+    "clean": "rm -rf node_modules apps/*/node_modules apps/*/dist packages/*/node_modules packages/*/dist"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0",
+    "prettier": "^3.3.0",
+    "eslint": "^9.0.0"
+  },
+  "engines": {
+    "node": ">=22.0.0",
+    "bun": ">=1.2.0"
+  },
+  "packageManager": "bun@1.2.0"
+}
@@ -0,0 +1,19 @@
+{
+  "name": "@zbrain/shared",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./types": "./src/types.ts",
+    "./schemas": "./src/schemas.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "zod": "^3.23.8"
+  }
+}
@@ -0,0 +1,2 @@
+export * from './types.js';
+export * from './schemas.js';
@@ -0,0 +1,63 @@
+import { z } from 'zod';
+
+export const UserRoleSchema = z.enum(['owner', 'admin', 'editor', 'viewer']);
+
+export const LoginRequestSchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8).max(256),
+  totpCode: z.string().regex(/^\d{6}$/).optional(),
+});
+
+export const CreateBrainSchema = z.object({
+  name: z.string().regex(/^[a-z0-9_]{1,32}$/, 'Только [a-z0-9_], до 32 символов'),
+  displayName: z.string().min(1).max(128),
+  description: z.string().max(1024).optional(),
+});
+
+export const MCPScopeSchema = z.string().regex(
+  /^mcp:(read|write|admin):[a-z0-9_*]{1,32}$/,
+  'Формат: mcp:<read|write|admin>:<brain-name>'
+) as z.ZodType<`mcp:${'read' | 'write' | 'admin'}:${string}`>;
+
+export const CreateTokenSchema = z.object({
+  name: z.string().min(1).max(128),
+  scopes: z.array(MCPScopeSchema).min(1).max(20),
+  ipAllowlist: z.array(z.string()).max(50).optional(),
+  expiresInDays: z.number().int().min(1).max(3650).nullable().optional(),
+});
+
+export const SourceConfigGitSchema = z.object({
+  type: z.literal('git'),
+  url: z.string().url(),
+  branch: z.string().default('main'),
+  subpath: z.string().optional(),
+  localPath: z.string(),
+});
+
+export const SourceConfigLocalDirSchema = z.object({
+  type: z.literal('local_dir'),
+  path: z.string(),
+});
+
+export const SourceConfigManualSchema = z.object({
+  type: z.literal('manual'),
+});
+
+export const SourceConfigSchema = z.discriminatedUnion('type', [
+  SourceConfigGitSchema,
+  SourceConfigLocalDirSchema,
+  SourceConfigManualSchema,
+]);
+
+export const CreateSourceSchema = z.object({
+  type: z.enum(['git', 'local_dir', 'manual']),
+  config: SourceConfigSchema,
+  schedule: z.string().nullable().optional(), // cron expression
+});
+
+export const CreateProjectSchema = z.object({
+  name: z.string().min(1).max(128),
+  slug: z.string().regex(/^[a-z0-9-]{1,64}$/, 'lowercase, цифры, дефисы'),
+  repoUrl: z.string().url().nullable().optional(),
+  description: z.string().max(1024).nullable().optional(),
+});
@@ -0,0 +1,145 @@
+// Shared types - используются и в API, и в Web
+// Источник правды для контракта между frontend и backend
+
+export type UserRole = 'owner' | 'admin' | 'editor' | 'viewer';
+
+export interface User {
+  id: string;
+  email: string;
+  displayName: string | null;
+  role: UserRole;
+  oauthProvider: 'yandex' | 'github' | null;
+  totpEnabled: boolean;
+  createdAt: string;
+  lastLoginAt: string | null;
+}
+
+export interface Brain {
+  id: string;
+  name: string;
+  displayName: string;
+  description: string | null;
+  postgresDatabase: string;
+  mcpInternalPort: number;
+  ownerUserId: string;
+  createdAt: string;
+
+  // Computed stats
+  stats?: BrainStats;
+}
+
+export interface BrainStats {
+  pageCount: number;
+  chunkCount: number;
+  embeddedCount: number;
+  linkCount: number;
+  diskSizeMB: number;
+  lastSyncAt: string | null;
+  healthStatus: 'healthy' | 'warning' | 'critical';
+  embeddingCoverage: number; // 0..1
+}
+
+export type SourceType = 'git' | 'local_dir' | 'manual';
+
+export interface Source {
+  id: string;
+  brainId: string;
+  type: SourceType;
+  config: SourceConfig;
+  schedule: string | null;
+  lastSyncAt: string | null;
+  lastSyncStatus: SyncStatus | null;
+  enabled: boolean;
+}
+
+export type SourceConfig =
+  | { type: 'git'; url: string; branch: string; subpath?: string; localPath: string }
+  | { type: 'local_dir'; path: string }
+  | { type: 'manual' };
+
+export type SyncStatus = 'idle' | 'running' | 'success' | 'failed';
+
+export type MCPScope = `mcp:${'read' | 'write' | 'admin'}:${string}`;
+
+export interface AccessToken {
+  id: string;
+  name: string;
+  prefix: string;
+  createdByUserId: string;
+  scopes: MCPScope[];
+  ipAllowlist: string[] | null;
+  createdAt: string;
+  expiresAt: string | null;
+  lastUsedAt: string | null;
+  lastUsedIp: string | null;
+  revokedAt: string | null;
+}
+
+export interface CreateTokenRequest {
+  name: string;
+  scopes: MCPScope[];
+  ipAllowlist?: string[];
+  expiresInDays?: number; // null = no expiration
+}
+
+export interface CreateTokenResponse {
+  token: AccessToken;
+  plaintext: string; // показывается ОДИН РАЗ
+}
+
+export interface Project {
+  id: string;
+  name: string;
+  slug: string;
+  repoUrl: string | null;
+  description: string | null;
+  ownerUserId: string;
+  createdAt: string;
+  connections: ProjectConnection[];
+}
+
+export interface ProjectConnection {
+  brainId: string;
+  brainName: string;
+  brainDisplayName: string;
+  tokenId: string;
+  tokenName: string;
+  scope: 'read' | 'write';
+}
+
+export interface ConnectSnippet {
+  client: 'claude-code' | 'cursor' | 'cli';
+  language: string;
+  filename: string | null;
+  content: string;
+  description: string;
+}
+
+export interface AuditEntry {
+  id: number;
+  actorType: 'user' | 'token';
+  actorId: string;
+  actorName: string;
+  action: string;
+  resourceType: string | null;
+  resourceId: string | null;
+  payload: Record<string, unknown> | null;
+  ip: string | null;
+  userAgent: string | null;
+  createdAt: string;
+}
+
+// API responses
+
+export interface PaginatedResponse<T> {
+  items: T[];
+  total: number;
+  page: number;
+  pageSize: number;
+}
+
+export interface ApiError {
+  error: string;
+  code: string;
+  details?: Record<string, unknown>;
+}
@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "declaration": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": false,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
@@ -0,0 +1,158 @@
+#!/usr/bin/env bash
+#
+# ZBrain Backup
+# ==============
+# Делает дамп всех Postgres БД (brainhub + все gbrain_*) и конфигов.
+# Шифрует архивы через age (нужен age и публичный ключ).
+#
+# Запуск из cron, например:
+#   0 3 * * *  root  /opt/zbrain/scripts/backup.sh
+
+set -euo pipefail
+
+# ============================================================
+# Конфигурация
+# ============================================================
+BACKUP_DIR="${BACKUP_DIR:-/var/backups/zbrain}"
+RETENTION_DAYS="${RETENTION_DAYS:-14}"
+AGE_RECIPIENT_FILE="${AGE_RECIPIENT_FILE:-/etc/zbrain/backup.age.pub}"
+LOG_FILE="${LOG_FILE:-/var/log/zbrain/backup.log}"
+ZBRAIN_CONFIG_DIR="/etc/zbrain"
+ZBRAIN_DATA_DIR="/var/lib/zbrain"
+
+DATE=$(date +%Y%m%d-%H%M%S)
+BACKUP_PATH="${BACKUP_DIR}/${DATE}"
+
+log() {
+    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*" | tee -a "$LOG_FILE"
+}
+
+err() {
+    echo "[$(date '+%Y-%m-%d %H:%M:%S')] ERROR: $*" | tee -a "$LOG_FILE" >&2
+}
+
+# ============================================================
+# Проверки
+# ============================================================
+[[ $EUID -eq 0 ]] || { err "Требуется root"; exit 1; }
+
+if ! command -v age &>/dev/null; then
+    err "age не установлен. apt install age"
+    exit 1
+fi
+
+if [[ ! -f "$AGE_RECIPIENT_FILE" ]]; then
+    err "Файл получателя age не найден: $AGE_RECIPIENT_FILE"
+    err "Создай ключ: age-keygen -o /etc/zbrain/backup.age"
+    err "И публичную часть в $AGE_RECIPIENT_FILE"
+    exit 1
+fi
+
+mkdir -p "$BACKUP_PATH" "$(dirname "$LOG_FILE")"
+chmod 700 "$BACKUP_DIR"
+
+log "=== ZBrain backup: $DATE ==="
+
+# ============================================================
+# Postgres dump (каждая БД отдельно)
+# ============================================================
+log "Дамп Postgres БД..."
+
+# Список всех ZBrain БД (brainhub + gbrain_*)
+DATABASES=$(sudo -u postgres psql -tAc "
+    SELECT datname FROM pg_database
+    WHERE datname = 'brainhub' OR datname LIKE 'gbrain_%'
+    ORDER BY datname
+")
+
+for db in $DATABASES; do
+    log "  ${db}"
+    dump_file="${BACKUP_PATH}/${db}.sql"
+    sudo -u postgres pg_dump --format=custom --compress=9 --file="${dump_file}.dump" "$db"
+
+    # Шифруем
+    age -R "$AGE_RECIPIENT_FILE" -o "${dump_file}.dump.age" "${dump_file}.dump"
+    rm "${dump_file}.dump"
+    log "  ✓ ${db}.sql.dump.age ($(du -h "${dump_file}.dump.age" | cut -f1))"
+done
+
+# pg_dumpall для глобальных объектов (roles, tablespaces)
+log "Дамп глобальных Postgres объектов..."
+sudo -u postgres pg_dumpall --globals-only > "${BACKUP_PATH}/_globals.sql"
+age -R "$AGE_RECIPIENT_FILE" -o "${BACKUP_PATH}/_globals.sql.age" "${BACKUP_PATH}/_globals.sql"
+rm "${BACKUP_PATH}/_globals.sql"
+
+# ============================================================
+# Конфиги
+# ============================================================
+log "Архив конфигов..."
+
+tar czf "${BACKUP_PATH}/config.tar.gz" \
+    -C / \
+    etc/zbrain \
+    etc/postgresql/16/main/postgresql.conf \
+    etc/postgresql/16/main/conf.d \
+    etc/postgresql/16/main/pg_hba.conf \
+    etc/systemd/system/zbrain-*.service \
+    etc/nginx 2>/dev/null || true
+
+age -R "$AGE_RECIPIENT_FILE" -o "${BACKUP_PATH}/config.tar.gz.age" "${BACKUP_PATH}/config.tar.gz"
+rm "${BACKUP_PATH}/config.tar.gz"
+
+log "✓ config.tar.gz.age"
+
+# ============================================================
+# gbrain data dir (config.json per-brain содержит пароли)
+# ============================================================
+log "Архив brain configs..."
+
+if [[ -d "$ZBRAIN_DATA_DIR/brains" ]]; then
+    tar czf "${BACKUP_PATH}/brains-meta.tar.gz" \
+        -C "$ZBRAIN_DATA_DIR" \
+        --exclude='brains/*/data' \
+        brains/
+    age -R "$AGE_RECIPIENT_FILE" -o "${BACKUP_PATH}/brains-meta.tar.gz.age" "${BACKUP_PATH}/brains-meta.tar.gz"
+    rm "${BACKUP_PATH}/brains-meta.tar.gz"
+    log "✓ brains-meta.tar.gz.age"
+fi
+
+# ============================================================
+# Манифест
+# ============================================================
+cat > "${BACKUP_PATH}/MANIFEST.txt" <<EOF
+ZBrain Backup
+=============
+Date: $(date -Iseconds)
+Hostname: $(hostname -f)
+Postgres version: $(sudo -u postgres psql -tAc 'SHOW server_version')
+
+Databases:
+$(echo "$DATABASES" | sed 's/^/  - /')
+
+Files:
+$(ls -lah "$BACKUP_PATH" | tail -n +2 | awk '{print "  - " $NF " (" $5 ")"}')
+
+Восстановление:
+  bash /opt/zbrain/scripts/restore.sh ${DATE}
+EOF
+
+# ============================================================
+# Размер итогового бэкапа
+# ============================================================
+TOTAL_SIZE=$(du -sh "$BACKUP_PATH" | cut -f1)
+log "✓ Backup завершён: $BACKUP_PATH ($TOTAL_SIZE)"
+
+# ============================================================
+# Retention - удаляем старые бэкапы
+# ============================================================
+log "Чистка бэкапов старше $RETENTION_DAYS дней..."
+find "$BACKUP_DIR" -maxdepth 1 -type d -name '????????-??????' -mtime +$RETENTION_DAYS -exec rm -rf {} \;
+log "✓ Чистка завершена"
+
+# ============================================================
+# (опционально) push на удалённое хранилище
+# ============================================================
+# rsync -avz "$BACKUP_PATH" backup@remote-host:/backups/zbrain/
+# или rclone copy "$BACKUP_PATH" "remote:zbrain-backups/${DATE}"
+
+log "=== Готово ==="
@@ -0,0 +1,485 @@
+#!/usr/bin/env bash
+#
+# ZBrain VM Bootstrap
+# ====================
+# Подготавливает чистую Ubuntu 22.04 VM к работе как ZBrain хост.
+# Устанавливает: Postgres 16 + pgvector, Node 22 LTS, Bun, Docker, gbrain.
+#
+# Использование:
+#   sudo bash scripts/bootstrap-vm.sh
+#
+# Предполагается: запуск от root на свежей Ubuntu 22.04 LTS.
+# Скрипт идемпотентный - можно перезапускать.
+
+set -euo pipefail
+
+# ============================================================
+# Конфигурация - правь под себя ПЕРЕД запуском
+# ============================================================
+ZBRAIN_USER="${ZBRAIN_USER:-zbrain}"
+ZBRAIN_HOME="/opt/zbrain"
+ZBRAIN_CONFIG_DIR="/etc/zbrain"
+ZBRAIN_DATA_DIR="/var/lib/zbrain"
+ZBRAIN_LOG_DIR="/var/log/zbrain"
+
+# FNA-прокси для исходящих запросов к OpenAI/Anthropic
+FNA_PROXY="${FNA_PROXY:-http://client_001:PASSWORD@fna.zetit.ru:3128}"
+
+POSTGRES_VERSION="16"
+NODE_VERSION="22"
+GBRAIN_VERSION="${GBRAIN_VERSION:-master}"  # потом закрепим тег после первого деплоя
+GBRAIN_REPO="${GBRAIN_REPO:-https://git.zetit.ru/zuevav/gbrain-mirror.git}"
+
+# RAM в гигабайтах (для тюнинга Postgres)
+TOTAL_RAM_GB="${TOTAL_RAM_GB:-8}"
+
+# ============================================================
+# Утилиты
+# ============================================================
+log() {
+    echo -e "\033[1;34m[$(date +'%H:%M:%S')] $*\033[0m"
+}
+
+err() {
+    echo -e "\033[1;31m[ERROR] $*\033[0m" >&2
+}
+
+require_root() {
+    if [[ $EUID -ne 0 ]]; then
+        err "Этот скрипт должен запускаться от root (sudo)."
+        exit 1
+    fi
+}
+
+check_ubuntu() {
+    if ! grep -q "Ubuntu 22.04" /etc/os-release 2>/dev/null; then
+        err "Скрипт рассчитан на Ubuntu 22.04 LTS."
+        err "Текущая система:"
+        cat /etc/os-release | grep PRETTY_NAME >&2 || true
+        read -p "Продолжить на свой страх и риск? [y/N] " -n 1 -r
+        echo
+        [[ $REPLY =~ ^[Yy]$ ]] || exit 1
+    fi
+}
+
+# ============================================================
+# Шаг 1: Базовые пакеты и обновления
+# ============================================================
+step_base_packages() {
+    log "Шаг 1: Базовые пакеты"
+
+    export DEBIAN_FRONTEND=noninteractive
+    apt-get update -qq
+    apt-get install -y -qq \
+        curl wget gnupg lsb-release ca-certificates \
+        build-essential git \
+        ufw fail2ban \
+        htop iotop net-tools \
+        unzip jq \
+        software-properties-common \
+        apt-transport-https \
+        chrony  # точное время для аудит-логов
+
+    log "Шаг 1: ✓"
+}
+
+# ============================================================
+# Шаг 2: Создание пользователя zbrain
+# ============================================================
+step_create_user() {
+    log "Шаг 2: Пользователь $ZBRAIN_USER"
+
+    if ! id "$ZBRAIN_USER" &>/dev/null; then
+        useradd --system --create-home --shell /bin/bash "$ZBRAIN_USER"
+        log "Создан пользователь $ZBRAIN_USER"
+    fi
+
+    mkdir -p "$ZBRAIN_HOME" "$ZBRAIN_CONFIG_DIR" "$ZBRAIN_DATA_DIR" "$ZBRAIN_LOG_DIR"
+    chown -R "$ZBRAIN_USER:$ZBRAIN_USER" "$ZBRAIN_HOME" "$ZBRAIN_DATA_DIR" "$ZBRAIN_LOG_DIR"
+    chmod 750 "$ZBRAIN_CONFIG_DIR"  # секреты - 750
+
+    log "Шаг 2: ✓"
+}
+
+# ============================================================
+# Шаг 3: Системные параметры (sysctl, swap, файрвол)
+# ============================================================
+step_system_tuning() {
+    log "Шаг 3: Системные параметры"
+
+    # Swap для защиты от OOM
+    if [[ ! -f /swapfile ]]; then
+        fallocate -l 4G /swapfile
+        chmod 600 /swapfile
+        mkswap /swapfile
+        swapon /swapfile
+        echo '/swapfile none swap sw 0 0' >> /etc/fstab
+        log "Создан swap 4G"
+    fi
+
+    # sysctl для Postgres + сети
+    cat > /etc/sysctl.d/99-zbrain.conf <<EOF
+# ZBrain system tuning
+vm.swappiness = 10
+vm.overcommit_memory = 2
+vm.overcommit_ratio = 80
+vm.dirty_background_ratio = 5
+vm.dirty_ratio = 10
+
+# Сетевые буферы
+net.core.rmem_max = 16777216
+net.core.wmem_max = 16777216
+net.ipv4.tcp_rmem = 4096 87380 16777216
+net.ipv4.tcp_wmem = 4096 65536 16777216
+
+# Защита
+net.ipv4.tcp_syncookies = 1
+net.ipv4.conf.all.rp_filter = 1
+EOF
+    sysctl -p /etc/sysctl.d/99-zbrain.conf >/dev/null
+
+    # UFW firewall
+    ufw --force reset >/dev/null
+    ufw default deny incoming
+    ufw default allow outgoing
+    ufw allow 22/tcp comment 'SSH'
+    ufw allow 80/tcp comment 'HTTP (redirect to HTTPS)'
+    ufw allow 443/tcp comment 'HTTPS'
+    # Postgres - ТОЛЬКО localhost, никаких ufw allow 5432!
+    ufw --force enable
+
+    log "Шаг 3: ✓"
+}
+
+# ============================================================
+# Шаг 4: PostgreSQL 16 + pgvector
+# ============================================================
+step_postgres() {
+    log "Шаг 4: PostgreSQL $POSTGRES_VERSION + pgvector"
+
+    # Репозиторий PGDG
+    if [[ ! -f /etc/apt/sources.list.d/pgdg.list ]]; then
+        sh -c 'echo "deb https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
+        wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | apt-key add -
+        apt-get update -qq
+    fi
+
+    apt-get install -y -qq \
+        postgresql-$POSTGRES_VERSION \
+        postgresql-contrib-$POSTGRES_VERSION \
+        postgresql-$POSTGRES_VERSION-pgvector \
+        postgresql-client-$POSTGRES_VERSION
+
+    # Тюнинг postgresql.conf под объём RAM
+    local pg_conf="/etc/postgresql/$POSTGRES_VERSION/main/postgresql.conf"
+    local shared_buffers=$((TOTAL_RAM_GB * 1024 / 4))   # 25% от RAM в MB
+    local effective_cache=$((TOTAL_RAM_GB * 1024 / 2))  # 50% от RAM в MB
+
+    cat > /etc/postgresql/$POSTGRES_VERSION/main/conf.d/zbrain.conf <<EOF
+# ZBrain Postgres tuning
+# Сгенерировано bootstrap-vm.sh для VM ${TOTAL_RAM_GB}GB RAM
+
+# Память
+shared_buffers = ${shared_buffers}MB
+effective_cache_size = ${effective_cache}MB
+maintenance_work_mem = 512MB
+work_mem = 32MB
+
+# Соединения
+max_connections = 100
+listen_addresses = 'localhost'
+
+# WAL
+wal_buffers = 16MB
+checkpoint_completion_target = 0.9
+min_wal_size = 1GB
+max_wal_size = 4GB
+
+# Параллелизм (для HNSW index build + сложных запросов)
+max_parallel_workers_per_gather = 2
+max_parallel_maintenance_workers = 2
+
+# SSD
+random_page_cost = 1.1
+effective_io_concurrency = 200
+
+# Логи
+log_min_duration_statement = 1000
+log_checkpoints = on
+log_connections = on
+log_disconnections = on
+log_lock_waits = on
+log_temp_files = 0
+log_line_prefix = '%t [%p] %u@%d '
+EOF
+
+    # pg_hba.conf - только localhost
+    cat > /etc/postgresql/$POSTGRES_VERSION/main/pg_hba.conf <<EOF
+# ZBrain pg_hba.conf
+local   all             postgres                                peer
+local   all             all                                     scram-sha-256
+host    all             all             127.0.0.1/32            scram-sha-256
+host    all             all             ::1/128                 scram-sha-256
+EOF
+
+    systemctl enable postgresql
+    systemctl restart postgresql
+
+    # Создание главной БД brainhub и расширений
+    sudo -u postgres psql -c "CREATE DATABASE brainhub;" 2>/dev/null || log "БД brainhub уже существует"
+    sudo -u postgres psql -d brainhub -c "CREATE EXTENSION IF NOT EXISTS vector;"
+    sudo -u postgres psql -d brainhub -c "CREATE EXTENSION IF NOT EXISTS pg_trgm;"
+    sudo -u postgres psql -d brainhub -c "CREATE EXTENSION IF NOT EXISTS pgcrypto;"
+
+    log "Шаг 4: ✓ Postgres работает, BD brainhub готова"
+    log "  ВАЖНО: создай пароли для пользователей postgres и brainhub:"
+    log "    sudo -u postgres psql"
+    log "    ALTER USER postgres PASSWORD '...';"
+    log "    CREATE USER brainhub WITH PASSWORD '...';"
+    log "    GRANT ALL PRIVILEGES ON DATABASE brainhub TO brainhub;"
+}
+
+# ============================================================
+# Шаг 5: Node.js 22 LTS + Bun
+# ============================================================
+step_node_bun() {
+    log "Шаг 5: Node.js $NODE_VERSION LTS + Bun"
+
+    # Node через NodeSource
+    if ! command -v node &>/dev/null || [[ "$(node -v)" != v${NODE_VERSION}* ]]; then
+        curl -fsSL https://deb.nodesource.com/setup_${NODE_VERSION}.x | bash -
+        apt-get install -y -qq nodejs
+    fi
+
+    # Bun (для gbrain)
+    if ! sudo -u "$ZBRAIN_USER" bash -c 'command -v bun' &>/dev/null; then
+        sudo -u "$ZBRAIN_USER" bash -c 'curl -fsSL https://bun.sh/install | bash'
+        # Добавим в PATH
+        sudo -u "$ZBRAIN_USER" bash -c 'echo "export PATH=\$HOME/.bun/bin:\$PATH" >> ~/.bashrc'
+    fi
+
+    log "  Node: $(node -v)"
+    log "  npm: $(npm -v)"
+    log "Шаг 5: ✓"
+}
+
+# ============================================================
+# Шаг 6: Docker + Compose
+# ============================================================
+step_docker() {
+    log "Шаг 6: Docker"
+
+    if ! command -v docker &>/dev/null; then
+        # Официальный репо Docker (не snap!)
+        install -m 0755 -d /etc/apt/keyrings
+        curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
+        chmod a+r /etc/apt/keyrings/docker.gpg
+        echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" > /etc/apt/sources.list.d/docker.list
+        apt-get update -qq
+        apt-get install -y -qq docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
+    fi
+
+    # zbrain в группу docker
+    usermod -aG docker "$ZBRAIN_USER"
+
+    systemctl enable docker
+    systemctl start docker
+
+    log "  Docker: $(docker --version)"
+    log "  Compose: $(docker compose version)"
+    log "Шаг 6: ✓"
+}
+
+# ============================================================
+# Шаг 7: gbrain (клонирование из mirror, установка зависимостей)
+# ============================================================
+step_gbrain() {
+    log "Шаг 7: gbrain (из $GBRAIN_REPO)"
+
+    local gbrain_dir="$ZBRAIN_DATA_DIR/gbrain"
+
+    if [[ ! -d "$gbrain_dir" ]]; then
+        sudo -u "$ZBRAIN_USER" git clone "$GBRAIN_REPO" "$gbrain_dir"
+    else
+        log "  gbrain уже склонирован в $gbrain_dir"
+        sudo -u "$ZBRAIN_USER" bash -c "cd '$gbrain_dir' && git fetch"
+    fi
+
+    sudo -u "$ZBRAIN_USER" bash -c "cd '$gbrain_dir' && git checkout '$GBRAIN_VERSION'"
+
+    # Установка зависимостей через bun (используем FNA-прокси)
+    log "  Устанавливаю зависимости gbrain (через FNA proxy)..."
+    sudo -u "$ZBRAIN_USER" bash -c "
+        export HTTPS_PROXY='$FNA_PROXY'
+        export HTTP_PROXY='$FNA_PROXY'
+        export PATH=\$HOME/.bun/bin:\$PATH
+        cd '$gbrain_dir' && bun install
+    "
+
+    log "Шаг 7: ✓"
+}
+
+# ============================================================
+# Шаг 8: Конфиг-файлы и шаблоны
+# ============================================================
+step_config_templates() {
+    log "Шаг 8: Шаблоны конфигов"
+
+    # .env шаблон
+    cat > "$ZBRAIN_CONFIG_DIR/env.example" <<'EOF'
+# ZBrain Environment Configuration
+# Скопируй в .env и заполни значения
+
+# === База данных ===
+DATABASE_URL=postgresql://brainhub:CHANGE_ME@localhost:5432/brainhub
+POSTGRES_ADMIN_URL=postgresql://postgres:CHANGE_ME@localhost:5432/postgres
+
+# === FNA Proxy (для исходящих к OpenAI/Anthropic) ===
+HTTPS_PROXY=http://client_001:PASSWORD@fna.zetit.ru:3128
+HTTP_PROXY=http://client_001:PASSWORD@fna.zetit.ru:3128
+NO_PROXY=localhost,127.0.0.1,.zetit.ru,.zetit.local
+
+# === API ключи ===
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+
+# === ZBrain ===
+ZBRAIN_BASE_URL=https://brain.zetit.ru
+ZBRAIN_INTERNAL_URL=http://brain.zetit.local
+SESSION_SECRET=GENERATE_RANDOM_64_CHARS
+JWT_SECRET=GENERATE_RANDOM_64_CHARS
+TOKEN_ENCRYPTION_KEY=GENERATE_RANDOM_32_BYTES_HEX
+
+# === OAuth ===
+YANDEX_OAUTH_CLIENT_ID=
+YANDEX_OAUTH_CLIENT_SECRET=
+GITHUB_OAUTH_CLIENT_ID=
+GITHUB_OAUTH_CLIENT_SECRET=
+
+# === Порты ===
+BRAINHUB_INTERNAL_PORT=3000
+BRAINHUB_PUBLIC_PORT=3010
+GBRAIN_PORT_RANGE_START=3001
+GBRAIN_PORT_RANGE_END=3099
+
+# === Логирование ===
+LOG_LEVEL=info
+LOG_FILE=/var/log/zbrain/brainhub.log
+EOF
+
+    chmod 640 "$ZBRAIN_CONFIG_DIR/env.example"
+    chown root:"$ZBRAIN_USER" "$ZBRAIN_CONFIG_DIR/env.example"
+
+    log "  Шаблон env: $ZBRAIN_CONFIG_DIR/env.example"
+    log "  Не забудь: cp $ZBRAIN_CONFIG_DIR/env.example $ZBRAIN_CONFIG_DIR/.env && chmod 600 $ZBRAIN_CONFIG_DIR/.env"
+    log "Шаг 8: ✓"
+}
+
+# ============================================================
+# Шаг 9: Самопроверка
+# ============================================================
+step_verify() {
+    log "Шаг 9: Самопроверка"
+
+    local errors=0
+
+    check() {
+        local name="$1"
+        local cmd="$2"
+        if eval "$cmd" &>/dev/null; then
+            log "  ✓ $name"
+        else
+            err "  ✗ $name (команда: $cmd)"
+            errors=$((errors+1))
+        fi
+    }
+
+    check "PostgreSQL запущен" "systemctl is-active postgresql"
+    check "Postgres доступен" "sudo -u postgres psql -c 'SELECT version()'"
+    check "pgvector установлен" "sudo -u postgres psql -d brainhub -c 'SELECT * FROM pg_extension WHERE extname = '\''vector'\'''  | grep -q vector"
+    check "Node.js установлен" "node --version"
+    check "Docker запущен" "systemctl is-active docker"
+    check "Bun установлен" "sudo -u $ZBRAIN_USER bash -c 'PATH=\$HOME/.bun/bin:\$PATH bun --version'"
+    check "gbrain склонирован" "test -d $ZBRAIN_DATA_DIR/gbrain"
+    check "UFW активен" "ufw status | grep -q 'Status: active'"
+    check "Swap включён" "swapon --show | grep -q swapfile"
+
+    if [[ $errors -gt 0 ]]; then
+        err "Обнаружено $errors ошибок. Проверь логи выше."
+        exit 1
+    fi
+
+    log "Шаг 9: ✓ Всё работает"
+}
+
+# ============================================================
+# Итоговый отчёт
+# ============================================================
+final_report() {
+    cat <<EOF
+
+╔════════════════════════════════════════════════════════════╗
+║                  ZBrain VM Bootstrap готов                 ║
+╚════════════════════════════════════════════════════════════╝
+
+Следующие шаги:
+
+1. Создай пароли для Postgres:
+   sudo -u postgres psql
+   ALTER USER postgres PASSWORD 'strong-password';
+   CREATE USER brainhub WITH PASSWORD 'another-strong-password';
+   GRANT ALL PRIVILEGES ON DATABASE brainhub TO brainhub;
+   \\q
+
+2. Скопируй и заполни .env:
+   sudo cp $ZBRAIN_CONFIG_DIR/env.example $ZBRAIN_CONFIG_DIR/.env
+   sudo chmod 600 $ZBRAIN_CONFIG_DIR/.env
+   sudo chown $ZBRAIN_USER:$ZBRAIN_USER $ZBRAIN_CONFIG_DIR/.env
+   sudo nano $ZBRAIN_CONFIG_DIR/.env
+
+3. Создай первый брейн:
+   sudo bash $ZBRAIN_HOME/scripts/create-brain.sh zetit "ZETIT MSP" 3001
+
+4. (опционально) Склонируй ZBrain код:
+   sudo -u $ZBRAIN_USER git clone git@git.zetit.ru:zuevav/ZBrain.git $ZBRAIN_HOME/app
+
+5. Запусти первый gbrain instance:
+   см. docs/DEPLOYMENT.md
+
+Параметры этой VM:
+  RAM: ${TOTAL_RAM_GB} GB
+  Postgres shared_buffers: $((TOTAL_RAM_GB * 1024 / 4)) MB
+  ZBrain home: $ZBRAIN_HOME
+  ZBrain data: $ZBRAIN_DATA_DIR
+  ZBrain config: $ZBRAIN_CONFIG_DIR
+  ZBrain logs: $ZBRAIN_LOG_DIR
+
+EOF
+}
+
+# ============================================================
+# Main
+# ============================================================
+main() {
+    require_root
+    check_ubuntu
+
+    log "Старт ZBrain VM bootstrap"
+    log "Целевая RAM: ${TOTAL_RAM_GB} GB"
+    log "FNA proxy: ${FNA_PROXY%%:*}://***"
+    echo
+
+    step_base_packages
+    step_create_user
+    step_system_tuning
+    step_postgres
+    step_node_bun
+    step_docker
+    step_gbrain
+    step_config_templates
+    step_verify
+
+    final_report
+}
+
+main "$@"
@@ -0,0 +1,273 @@
+#!/usr/bin/env bash
+#
+# Создание нового gbrain instance
+# ================================
+# Создаёт изолированную БД + пользователя Postgres + systemd unit
+# для gbrain serve --http на отдельном порту.
+#
+# Использование:
+#   sudo bash scripts/create-brain.sh <name> "<display name>" <port>
+#
+# Примеры:
+#   sudo bash scripts/create-brain.sh zetit "ZETIT MSP" 3001
+#   sudo bash scripts/create-brain.sh telerapharma "TeleraPharma" 3002
+#   sudo bash scripts/create-brain.sh personal "Personal" 3003
+#   sudo bash scripts/create-brain.sh community "Smolenskaya 10" 3004
+
+set -euo pipefail
+
+# ============================================================
+# Аргументы
+# ============================================================
+if [[ $# -lt 3 ]]; then
+    cat <<EOF
+Usage: $0 <name> "<display-name>" <port>
+
+Arguments:
+  name          slug-имя брейна (только [a-z0-9_], <=32 символов)
+  display-name  человекочитаемое имя в кавычках
+  port          TCP-порт для gbrain serve --http (3001-3099)
+
+Example:
+  $0 zetit "ZETIT MSP" 3001
+EOF
+    exit 1
+fi
+
+BRAIN_NAME="$1"
+BRAIN_DISPLAY="$2"
+BRAIN_PORT="$3"
+
+# Валидация
+if [[ ! "$BRAIN_NAME" =~ ^[a-z0-9_]{1,32}$ ]]; then
+    echo "ERROR: name должно содержать только [a-z0-9_] и быть не длиннее 32 символов" >&2
+    exit 1
+fi
+
+if [[ ! "$BRAIN_PORT" =~ ^[0-9]+$ ]] || [[ $BRAIN_PORT -lt 3001 ]] || [[ $BRAIN_PORT -gt 3099 ]]; then
+    echo "ERROR: port должен быть числом в диапазоне 3001-3099" >&2
+    exit 1
+fi
+
+# ============================================================
+# Константы
+# ============================================================
+ZBRAIN_USER="zbrain"
+ZBRAIN_DATA_DIR="/var/lib/zbrain"
+ZBRAIN_CONFIG_DIR="/etc/zbrain"
+GBRAIN_DIR="$ZBRAIN_DATA_DIR/gbrain"
+
+DB_NAME="gbrain_${BRAIN_NAME}"
+DB_USER="gbrain_${BRAIN_NAME}"
+SYSTEMD_UNIT="zbrain-gbrain-${BRAIN_NAME}"
+BRAIN_HOME="$ZBRAIN_DATA_DIR/brains/$BRAIN_NAME"
+
+log() { echo -e "\033[1;34m[$(date +'%H:%M:%S')] $*\033[0m"; }
+err() { echo -e "\033[1;31m[ERROR] $*\033[0m" >&2; }
+
+# ============================================================
+# Проверки
+# ============================================================
+[[ $EUID -eq 0 ]] || { err "Требуется sudo"; exit 1; }
+[[ -d "$GBRAIN_DIR" ]] || { err "gbrain не установлен. Запусти сначала bootstrap-vm.sh"; exit 1; }
+[[ -f "$ZBRAIN_CONFIG_DIR/.env" ]] || { err "$ZBRAIN_CONFIG_DIR/.env не существует"; exit 1; }
+
+# Проверка занятости порта
+if ss -tln | grep -q ":${BRAIN_PORT} "; then
+    err "Порт $BRAIN_PORT уже занят"
+    exit 1
+fi
+
+# Проверка существования
+if sudo -u postgres psql -lqt | cut -d \| -f 1 | grep -qw "$DB_NAME"; then
+    err "БД $DB_NAME уже существует"
+    exit 1
+fi
+
+# ============================================================
+# Создание Postgres пользователя и БД
+# ============================================================
+log "Создаю Postgres пользователя $DB_USER и БД $DB_NAME"
+
+DB_PASSWORD=$(openssl rand -hex 24)
+
+sudo -u postgres psql <<EOF
+CREATE USER ${DB_USER} WITH PASSWORD '${DB_PASSWORD}';
+CREATE DATABASE ${DB_NAME} OWNER ${DB_USER};
+GRANT ALL PRIVILEGES ON DATABASE ${DB_NAME} TO ${DB_USER};
+EOF
+
+sudo -u postgres psql -d "$DB_NAME" <<EOF
+CREATE EXTENSION IF NOT EXISTS vector;
+CREATE EXTENSION IF NOT EXISTS pg_trgm;
+CREATE EXTENSION IF NOT EXISTS pgcrypto;
+GRANT ALL ON SCHEMA public TO ${DB_USER};
+EOF
+
+log "✓ БД создана"
+
+# ============================================================
+# Brain home directory + конфиг
+# ============================================================
+log "Создаю $BRAIN_HOME"
+mkdir -p "$BRAIN_HOME"
+chown -R "$ZBRAIN_USER:$ZBRAIN_USER" "$BRAIN_HOME"
+
+# gbrain config
+cat > "$BRAIN_HOME/config.json" <<EOF
+{
+  "name": "${BRAIN_NAME}",
+  "display_name": "${BRAIN_DISPLAY}",
+  "database_url": "postgresql://${DB_USER}:${DB_PASSWORD}@localhost:5432/${DB_NAME}",
+  "port": ${BRAIN_PORT},
+  "data_dir": "${BRAIN_HOME}/data"
+}
+EOF
+chown "$ZBRAIN_USER:$ZBRAIN_USER" "$BRAIN_HOME/config.json"
+chmod 600 "$BRAIN_HOME/config.json"
+
+mkdir -p "$BRAIN_HOME/data"
+chown -R "$ZBRAIN_USER:$ZBRAIN_USER" "$BRAIN_HOME/data"
+
+log "✓ Конфиг $BRAIN_HOME/config.json"
+
+# ============================================================
+# Инициализация gbrain схемы
+# ============================================================
+log "Инициализирую gbrain схему"
+
+# Загружаем .env для FNA proxy + OpenAI/Anthropic ключей
+set -a
+source "$ZBRAIN_CONFIG_DIR/.env"
+set +a
+
+sudo -u "$ZBRAIN_USER" bash -c "
+    export PATH=\$HOME/.bun/bin:\$PATH
+    export HTTPS_PROXY='${HTTPS_PROXY}'
+    export HTTP_PROXY='${HTTP_PROXY}'
+    export OPENAI_API_KEY='${OPENAI_API_KEY}'
+    export ANTHROPIC_API_KEY='${ANTHROPIC_API_KEY}'
+    cd '$GBRAIN_DIR' && \
+    bun run gbrain init --url 'postgresql://${DB_USER}:${DB_PASSWORD}@localhost:5432/${DB_NAME}' --yes
+"
+
+log "✓ Схема инициализирована"
+
+# ============================================================
+# Systemd unit
+# ============================================================
+log "Создаю systemd unit $SYSTEMD_UNIT"
+
+cat > "/etc/systemd/system/${SYSTEMD_UNIT}.service" <<EOF
+[Unit]
+Description=ZBrain gbrain instance: ${BRAIN_DISPLAY}
+Documentation=https://git.zetit.ru/zuevav/ZBrain
+After=postgresql.service network-online.target
+Wants=network-online.target
+Requires=postgresql.service
+
+[Service]
+Type=simple
+User=${ZBRAIN_USER}
+Group=${ZBRAIN_USER}
+WorkingDirectory=${GBRAIN_DIR}
+
+# Окружение
+Environment="PATH=/home/${ZBRAIN_USER}/.bun/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+Environment="DATABASE_URL=postgresql://${DB_USER}:${DB_PASSWORD}@localhost:5432/${DB_NAME}"
+Environment="GBRAIN_DATA_DIR=${BRAIN_HOME}/data"
+EnvironmentFile=${ZBRAIN_CONFIG_DIR}/.env
+
+# Запуск gbrain в HTTP MCP режиме
+ExecStart=/home/${ZBRAIN_USER}/.bun/bin/bun run gbrain serve --http --port ${BRAIN_PORT} --bind 127.0.0.1
+
+# Restart policy
+Restart=on-failure
+RestartSec=10s
+StartLimitInterval=300
+StartLimitBurst=5
+
+# Security hardening
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=${BRAIN_HOME} /var/log/zbrain
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictNamespaces=true
+RestrictRealtime=true
+LockPersonality=true
+
+# Resource limits
+LimitNOFILE=65536
+MemoryMax=2G
+CPUQuota=200%
+
+# Логи
+StandardOutput=append:/var/log/zbrain/${BRAIN_NAME}.log
+StandardError=append:/var/log/zbrain/${BRAIN_NAME}.error.log
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+systemctl daemon-reload
+systemctl enable "$SYSTEMD_UNIT"
+systemctl start "$SYSTEMD_UNIT"
+
+sleep 3
+
+if systemctl is-active --quiet "$SYSTEMD_UNIT"; then
+    log "✓ Сервис запущен: $SYSTEMD_UNIT"
+else
+    err "Сервис не стартовал. Логи:"
+    journalctl -u "$SYSTEMD_UNIT" -n 20 --no-pager
+    exit 1
+fi
+
+# ============================================================
+# Проверка health
+# ============================================================
+log "Проверяю доступность на localhost:$BRAIN_PORT"
+
+if curl -sf "http://localhost:${BRAIN_PORT}/health" >/dev/null 2>&1; then
+    log "✓ Health check OK"
+else
+    log "⚠ Health endpoint недоступен (возможно gbrain ещё стартует или endpoint называется иначе)"
+fi
+
+# ============================================================
+# Финальный отчёт
+# ============================================================
+cat <<EOF
+
+╔════════════════════════════════════════════════════════════╗
+║                  Брейн '${BRAIN_NAME}' создан                  
+╚════════════════════════════════════════════════════════════╝
+
+  Display name:    ${BRAIN_DISPLAY}
+  Postgres DB:     ${DB_NAME}
+  Postgres user:   ${DB_USER}
+  Port:            ${BRAIN_PORT}
+  Home:            ${BRAIN_HOME}
+  Systemd unit:    ${SYSTEMD_UNIT}
+  MCP endpoint:    http://localhost:${BRAIN_PORT}/mcp
+
+Полезные команды:
+  systemctl status ${SYSTEMD_UNIT}
+  journalctl -u ${SYSTEMD_UNIT} -f
+  tail -f /var/log/zbrain/${BRAIN_NAME}.log
+
+Импорт данных:
+  sudo -u ${ZBRAIN_USER} bash -c '
+    export PATH=\$HOME/.bun/bin:\$PATH
+    export DATABASE_URL="postgresql://${DB_USER}:***@localhost:5432/${DB_NAME}"
+    cd ${GBRAIN_DIR} && bun run gbrain import /path/to/markdown/
+  '
+
+DB password сохранён в:
+  ${BRAIN_HOME}/config.json (доступ только root и ${ZBRAIN_USER})
+
+EOF
@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+#
+# ZBrain Restore
+# ===============
+# Восстанавливает ZBrain из бэкапа созданного backup.sh.
+#
+# Использование:
+#   sudo bash scripts/restore.sh <backup-timestamp>
+#
+# Где <backup-timestamp> - имя папки в BACKUP_DIR (например, 20260520-031500)
+#
+# ВАЖНО: для расшифровки нужен приватный age ключ.
+# Положи его на VM перед запуском restore (например, /tmp/backup.age).
+# Скрипт спросит путь к ключу.
+
+set -euo pipefail
+
+# ============================================================
+# Конфигурация
+# ============================================================
+BACKUP_DIR="${BACKUP_DIR:-/var/backups/zbrain}"
+LOG_FILE="/var/log/zbrain/restore.log"
+
+log() {
+    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*" | tee -a "$LOG_FILE"
+}
+
+err() {
+    echo "[$(date '+%Y-%m-%d %H:%M:%S')] ERROR: $*" | tee -a "$LOG_FILE" >&2
+}
+
+# ============================================================
+# Аргументы
+# ============================================================
+if [[ $# -lt 1 ]]; then
+    echo "Usage: $0 <backup-timestamp>"
+    echo ""
+    echo "Available backups:"
+    ls -1 "$BACKUP_DIR" 2>/dev/null | grep -E '^[0-9]{8}-[0-9]{6}$' | sort -r | head -10
+    exit 1
+fi
+
+TIMESTAMP="$1"
+BACKUP_PATH="$BACKUP_DIR/$TIMESTAMP"
+
+[[ -d "$BACKUP_PATH" ]] || { err "Бэкап не найден: $BACKUP_PATH"; exit 1; }
+[[ $EUID -eq 0 ]] || { err "Требуется sudo"; exit 1; }
+
+# ============================================================
+# Age ключ для расшифровки
+# ============================================================
+read -p "Путь к age приватному ключу: " AGE_KEY_PATH
+[[ -f "$AGE_KEY_PATH" ]] || { err "Файл не найден: $AGE_KEY_PATH"; exit 1; }
+
+# Тест ключа
+if ! age -d -i "$AGE_KEY_PATH" "$BACKUP_PATH/_globals.sql.age" > /dev/null 2>&1; then
+    err "Не могу расшифровать с этим ключом"
+    exit 1
+fi
+
+# ============================================================
+# Подтверждение
+# ============================================================
+cat <<EOF
+
+╔════════════════════════════════════════════════════════════╗
+║                  ВНИМАНИЕ                                  ║
+║                                                            ║
+║  Восстановление перезапишет все существующие БД ZBrain!    ║
+║                                                            ║
+║  Бэкап: $TIMESTAMP                                ║
+║  Файлы:                                                    ║
+$(ls "$BACKUP_PATH" | sed 's/^/║    /' | awk '{printf "%-60s║\n", $0}')
+║                                                            ║
+╚════════════════════════════════════════════════════════════╝
+
+EOF
+
+read -p "Введите 'YES' для продолжения: " CONFIRM
+[[ "$CONFIRM" == "YES" ]] || { log "Отменено пользователем"; exit 0; }
+
+log "=== Начинаю restore из $TIMESTAMP ==="
+
+# ============================================================
+# Восстановление глобальных объектов
+# ============================================================
+log "Восстанавливаю глобальные Postgres объекты..."
+age -d -i "$AGE_KEY_PATH" -o /tmp/_globals.sql "$BACKUP_PATH/_globals.sql.age"
+sudo -u postgres psql -f /tmp/_globals.sql 2>&1 | tee -a "$LOG_FILE" | grep -v "already exists" || true
+rm /tmp/_globals.sql
+log "✓ Globals"
+
+# ============================================================
+# Восстановление БД
+# ============================================================
+for encrypted_dump in "$BACKUP_PATH"/*.sql.dump.age; do
+    [[ -f "$encrypted_dump" ]] || continue
+    db_name=$(basename "$encrypted_dump" .sql.dump.age)
+    [[ "$db_name" == "_globals" ]] && continue
+
+    log "Восстанавливаю $db_name..."
+
+    # Дропаем существующую БД (если есть)
+    sudo -u postgres dropdb --if-exists "$db_name"
+
+    # Создаём пустую
+    sudo -u postgres createdb "$db_name"
+
+    # Расшифровываем dump
+    dump_file="/tmp/${db_name}.dump"
+    age -d -i "$AGE_KEY_PATH" -o "$dump_file" "$encrypted_dump"
+
+    # Восстанавливаем
+    sudo -u postgres pg_restore --dbname="$db_name" --no-owner --role=postgres "$dump_file" 2>&1 | tee -a "$LOG_FILE" || true
+
+    rm "$dump_file"
+    log "✓ $db_name"
+done
+
+# ============================================================
+# Конфиги (опционально)
+# ============================================================
+read -p "Восстановить конфиги? (включая /etc/zbrain) [y/N]: " RESTORE_CONFIG
+if [[ "$RESTORE_CONFIG" =~ ^[Yy]$ ]]; then
+    log "Восстанавливаю конфиги..."
+    age -d -i "$AGE_KEY_PATH" -o /tmp/config.tar.gz "$BACKUP_PATH/config.tar.gz.age"
+    tar xzf /tmp/config.tar.gz -C /
+    rm /tmp/config.tar.gz
+    log "✓ Конфиги"
+
+    if [[ -f "$BACKUP_PATH/brains-meta.tar.gz.age" ]]; then
+        log "Восстанавливаю метаданные брейнов..."
+        age -d -i "$AGE_KEY_PATH" -o /tmp/brains-meta.tar.gz "$BACKUP_PATH/brains-meta.tar.gz.age"
+        tar xzf /tmp/brains-meta.tar.gz -C /var/lib/zbrain/
+        rm /tmp/brains-meta.tar.gz
+        log "✓ Brain configs"
+    fi
+fi
+
+# ============================================================
+# Финал
+# ============================================================
+log "=== Restore завершён ==="
+log ""
+log "Следующие шаги:"
+log "  1. Перезапусти системные сервисы:"
+log "     sudo systemctl restart 'zbrain-gbrain-*.service'"
+log "  2. Перезапусти brainhub:"
+log "     cd /opt/zbrain/deploy/docker && docker compose restart"
+log "  3. Проверь health endpoint каждого сервиса"
+log ""
+log "ВАЖНО: удали age приватный ключ с этой VM после restore!"
+log "  shred -u $AGE_KEY_PATH"