dedinit.ru/AGENTS.md

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 из последнего поста как базу — единый стиль.
• Хэштеги (поле tags и хэштеги в тексте) — ТОЛЬКО строчными буквами.
• Блочный код с подсветкой — обязателен там, где нужен (цель проекта).

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

# ЕДИНСТВЕННЫЙ способ деплоя — 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) и прошлые сессии.