chore(docs): уборка структуры — вся документация в docs/, краткий README, добавлен AGENTS.md

- AGENTS.md: правила проекта (структура доков, стек, статьи, деплой, git, openspec, проверки) - README.md: сокращён до введения + указателей на docs/ - docs/: DEPLOY_INSTRUCTIONS, ROADMAP, PAPERMOD_PARAMS, QWEN, gitea-setup, Telegram_frontend, ssh_setup, archive/PROJECT_SUMMARY (из .qwen/) - tools/: winscp_script.txt переехал из корня к deploy_sftp.py - Makefile и deploy_sftp.py: ссылки на docs/DEPLOY_INSTRUCTIONS.md
2026-09-12 09:58:09 +00:00
parent 80eb3c709d
commit d426aa39ed
13 changed files with 145 additions and 103 deletions
@@ -0,0 +1,87 @@
+# AGENTS.md — правила работы с проектом dedinit.ru
+
+## Общие принципы
+
+1. Взаимодействие и документация — на русском языке.
+2. Все важные решения и изменения фиксируются в README.md (кратко) и соответствующих документах в `docs/`.
+3. Перед применением изменений проверяется корректность принятых решений.
+4. Цель — максимально быстро публиковать контент без поломки сайта.
+
+## Структура документации
+
+- `README.md` — ТОЛЬКО краткое введение в проект для репозитория:
+  что это, стек, быстрый старт (сборка/деплой) и указатели на `docs/`.
+  Никакой подробной документации и истории изменений в README не держим.
+- `docs/` — вся подробная документация проекта:
+  инструкции, справочники, дорожные карты, заметки об опыте настройки.
+- `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).
+  Правки контента/кода — через openspec-скиллы из `.hermes/skills/`
+  (propose → design → apply → archive).
+- Проверочные действия перед этапами: `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) и прошлые сессии.