# AGENTS.md — правила работы с проектом dedinit.ru

## Общие принципы

1. Взаимодействие и документация — на русском языке.
2. Все важные решения и изменения фиксируются в README.md (кратко) и соответствующих документах в `docs/`.
3. Перед применением изменений проверяется корректность принятых решений.
4. Цель — максимально быстро публиковать контент без поломки сайта.

## Структура документации

- `README.md` — ТОЛЬКО краткое введение в проект для репозитория:
  что это, стек, быстрый старт (сборка/деплой) и указатели на `docs/`.
  Никакой подробной документации и истории изменений в README не держим.
- `docs/` — вся подробная документация проекта:
  инструкции, справочники, дорожные карты, заметки об опыте настройки.
- **Файлы проекта (статус/требования/задачи/журнал) — тоже в `docs/`:**
  `docs/STATUS.md` (текущее состояние), `docs/PRD.md` (требования),
  `docs/TODO.md` (журнал задач), `docs/WALKTHROUGH.md` (капитанский журнал).
  При закрытии сессии обновляются именно они.
- `AGENTS.md` — правила работы для агентов (этот файл).
- Подробная эксплуатационная документация НЕ должна лежать в корне репозитория.
  Новые документы создавать только в `docs/`.

## Технологический стек

| Параметр | Значение |
|----------|----------|
| Генератор | Hugo Extended 0.165.x |
| Тема | rDedInit (форк PaperMod) |
| Язык | Русский (ru-ru), timeZone Europe/Moscow |
| Формат статей | Bundle: `content/posts/<name>/index.md` (+ hero.svg и др.) |
| Git-хостинг | gitverse.ru — источник истины (kpa39l/dedinit.ru) |
| Деплой | SFTP на kpa39l.myjino.ru:2222 |

## Статьи (контент)

- Новые статьи: `content/posts/<YYYYMMDD - slug>/index.md`.
- Frontmatter: `date`, `lastmod` — в прошлом (Hugo молча не публикует
  страницы с датой в будущем), `draft: false`, `title`, `slug`.
- hero.svg для статьи: `viewBox="0 0 1200 400"`, фон `#0a0c10`,
  паттерн-гексагон `#1a2332`, заголовок моноширинный `#58a6ff`.
  Копировать hero.svg из последнего поста как базу — единый стиль.
- Блочный код с подсветкой — обязателен там, где нужен (цель проекта).

## Сборка и деплой

```bash
# ЕДИНСТВЕННЫЙ способ деплоя — make deploy. Не заменять на rsync/ssh-exec:
# аккаунт Jino SFTP-only (exec request failed on channel 0).
export SSHPASS='<пароль SFTP>'
make deploy            # hugo --minify + mirror public/ → /dedinit.ru
make deploy-dry-run    # симуляция деплоя
make build             # только сборка
make help              # все команды
```

- `public/`, `.venv/`, `.hermes/` — в git не попадают (.gitignore).
- Пароль SFTP в открытом виде в репозиторий НЕ коммитить
  (winscp_script.txt с паролем был вынесен из корня — см. `tools/`).

## Git

- Ветка `main`, источник истины — gitverse.ru, пуши через SSH
  (`git@gitverse.ru:kpa39l/dedinit.ru.git`).
- Gitea (bigbox) — pull-mirror, туда отдельно не пушить.
- Коммиты — короткие, по смыслу изменений.
- Секреты и пароли в коммиты не добавлять.

## Процессы и планирование

- **ВСЕ задачи по изменению проекта выполняются через OpenSpec**:
  `openspec/` (specs + changes). Порядок: propose → design → apply → archive.
  Новые изменения — только через openspec-скиллы из `.hermes/skills/`;
  напрямую без OpenSpec ничего не менять (кроме `docs/`-правок и уборки).
- Проверочные действия перед этапами: `hugo version`, `make build`,
  контроль `hugo.toml`, `make deploy-dry-run`.

## Обязательные проверки перед публикацией статьи

1. `date` НЕ в будущем (иначе Hugo молча не публикует, без предупреждения).
2. `make build` проходит без ошибок.
3. Статья есть в сборке: `ls public/<год>/<slug>/index.html`,
   `grep -o '<title>[^<]*</title>'`, `grep -o 'hero.svg'`.
4. `git push origin main`, затем при необходимости `make deploy`.

## Правила пользователя

- Краткие статус-отчёты на русском языке.
- Тихие watchdog'и: уведомлять только при реальной проблеме.
- НЕ удалять и не перезаписывать данные пользователя без явного подтверждения.
- Перед действиями — читать доки проекта (STATUS/PRD/WALKTHROUGH/TODO.md, openspec) и прошлые сессии.