# Claude — правила работы с проектом zov-tech

## 🧠 Принципы работы Claude в этом проекте

1. **ОСПАРИВАЙ РЕШЕНИЯ.** Если подход плохой — скажи прямо. Не соглашайся только потому что попросили. Лучше короткий аргумент «это плохо потому что…» чем молчаливое выполнение.

2. **СТРУКТУРА КАЖДОГО ОТВЕТА:**
   - ✅ Что сделано
   - ❓ Что нужно от тебя (если нужно что-то)
   - ➡️ Следующий шаг

3. **ПОСЛЕ КАЖДОЙ ЗАДАЧИ** — предлагай что улучшить или автоматизировать. Одно-два конкретных предложения, не список на 10 пунктов.

4. **ВСЁ ЧТО МОЖЕТ ДЕЛАТЬ CLAUDE — ДЕЛАЕТ CLAUDE.** Цель — освободить время владельца. Не спрашивать разрешения на очевидные технические шаги. Делать, потом сообщать.

---

## ⚠️ ОБЯЗАТЕЛЬНЫЙ АГЕНТ ПРОВЕРКИ ПЕРЕД ЛЮБЫМ UI/CSS КОММИТОМ

**Перед каждым `git commit` с изменениями в `miniapp/` — запустить:**
```
/project:ui-check
```
Агент читает изменённые файлы, проходит чеклист и выдаёт вердикт.
**Коммит только после вердикта ✅.**

---

## Детальный чеклист (используется агентом `/project:ui-check`)

Перед каждым `git commit` с изменениями в `miniapp/` — пройти все пункты:

### 1. Цвет и читаемость
- [ ] Используется ли `color: transparent` для скрытия текста? (НЕ `var(--card)` — она зависит от Telegram-темы и может быть не нужным цветом)
- [ ] Нет ли текста, где `color` и `background` одинаковы только в светлой теме?
- [ ] Проверены ли все 4 темы: **Default, Foundry, Boardroom, Atelier** — в каждой из них `--card`, `--paper`, `--ink`, `--muted` могут быть разными
- [ ] Если добавляется новый CSS-класс — указан ли явный `color:` (не наследование)?

### 2. Новые CSS-классы
- [ ] Для каждого нового класса (`.foo`) — проверить, что стили явно определены и не полагаются на наследование от `body`
- [ ] Добавлены ли стили для всех тем (ищи блоки `[data-theme="foundry"]`, `[data-theme="boardroom"]`, `[data-theme="atelier"]` в styles.css)?

### 3. Версия кэша
- [ ] Бамп `?v=` в `index.html` для каждого изменённого `.css` или `.js` файла
- [ ] Формат: `?v=YYYYMMDD[буква]` — буква растёт по алфавиту в течение дня

### 4. Деплой
- [ ] После `git push` — GitHub Actions деплоит ~1-2 мин (смотреть на вкладке Actions в GitHub)
- [ ] VPS (бот + бэкенд) обновляется отдельно: `ssh root@94.241.170.144 "cd /opt/zov-tech && git pull && docker compose -f deploy/docker-compose.yml up -d --build bot"`

---

## Архитектура проекта

```
miniapp/          → статика, деплой через GitHub Pages (github.com/wasrusgen/zov-tech)
bot/              → Telegram-бот, работает на VPS 94.241.170.144
backend-py/       → FastAPI-бэкенд, работает на VPS
deploy/           → docker-compose.yml, Caddyfile.snippet
```

- **MINIAPP_URL**: `https://wasrusgen.github.io/zov-tech/`
- **API**: `https://api.wasrusgen1.pro`
- **VPS SSH**: `ssh -i ~/.ssh/zov_vps_ed25519 root@94.241.170.144`

## CSS-переменные по темам

| Переменная | Default (светлая) | Foundry | Boardroom | Atelier |
|---|---|---|---|---|
| `--card` | `tg-section-bg` (≈белый) | `#EAE3CC` | `#EDE5D0` | `#FFFFFF` |
| `--ink` | `tg-text-color` | `#1A150E` | `#1A150E` | тёмный |
| `--muted` | серый | `#7A6E5F` | `#6B6256` | серый |

> ⚠️ `var(--card)` в дефолтной теме читается из `--tg-theme-section-bg-color` Telegram.
> В тёмном Telegram-клиенте это НЕ белый цвет. Для полного скрытия текста — только `color: transparent`.

## Типичные ошибки (уже были)

1. **`color: var(--card)` для скрытия текста** → не работает: `--card` зависит от Telegram-темы и может не совпадать с фактическим фоном
2. **`color: transparent` для скрытия текста** → НЕ использовать: создаёт "дырку" — буквы просвечивают фон страницы за карточкой, силуэт текста виден
3. **Правильный способ скрыть текст** → `opacity: 0` — элемент невидим полностью, место сохраняет, никаких артефактов
4. **Новый JS-класс без CSS** → текст наследует `color: var(--ink)` от body → видим на фоне карточки
3. **Не бамп версии** → WebView грузит старый кэш → изменения не видны
4. **`var(--card)` как фон у hero-секции** → при изменении темы текст становится невидимым (светлый текст на светлом фоне). Решение: явный `color: var(--ink)` inline