dedinit.ru/docs/WALKTHROUGH.md

WALKTHROUGH — dedinit.ru (капитанский журнал)

2026-09-12 — Уборка структуры репозитория + OpenSpec

Контекст

Репозиторий dedinit.ru (Hugo, тема rDedInit/PaperMod) имел документацию в корне; задача — привести к стандарту: README краткий, вся документация в docs/, AGENTS.md для агентов.

Что сделано

1. AGENTS.md создан (корень) — правила: русский язык, структура (README краткий + docs/), стек (Hugo Extended, тема rDedInit, gitverse источник истины, деплой SFTP), статьи (bundle, date в прошлом, hero.svg), деплой только make deploy, git-правила, OpenSpec-процесс, проверки перед публикацией.
2. Документация перенесена в docs/ (git mv): DEPLOY_INSTRUCTIONS.md, ROADMAP.md, PAPERMOD_PARAMS.md, QWEN.md, gitea-setup.md, ssh_setup_instructions.md, Telegram_frontend.md.
3. Промежуточные файлы: .qwen/PROJECT_SUMMARY.md → docs/archive/, winscp_script.txt → tools/.
4. README.md переписан кратко (55 строк): суть, быстрый старт, структура, указатели на docs/, конвенции. История убрана.
5. Ссылки обновлены: Makefile и tools/deploy_sftp.py → docs/DEPLOY_INSTRUCTIONS.md; docs/QWEN.md, docs/ROADMAP.md — пути.
6. Коммиты/пуш: d426aa3 (уборка), 0f4d6da (правило OpenSpec в AGENTS.md), f07bffe (openspec-propose локализации).

OpenSpec — задача локализации

• Change: openspec/changes/localize-i18n-ru/ (propose завершён, валиден).
• Артефакты: proposal.md (зачем), specs/i18n/spec.md (требования + сценарии), design.md (решения), tasks.md (5 задач).
• Питфол синтаксиса: openspec validate --change <name> — ОШИБКА (unknown option '--change'). Правильно: openspec validate <name>. Это зафиксировано во всех 6 локальных openspec-скиллах (.hermes/skills/openspec-*/SKILL.md).

Файлы проекта

• Согласно правилу «вся документация в docs/» — файлы проекта лежат в docs/:
  • docs/STATUS.md — текущее состояние, сделано, следующие шаги, как проверить.
  • docs/PRD.md — требования, границы, критерии готовности.
  • docs/TODO.md — журнал задач (история, статусы).
  • docs/WALKTHROUGH.md — этот журнал.

Как повторить / проверить

cd /opt/dedinit.ru
make build            # сборка
openspec validate localize-i18n-ru   # валидация active-change
git pull              # обновление (origin = gitverse)

Известные подводные камни

• .hermes/ игнорируется git (.gitignore) — openspec-скиллы не коммитятся.
• Секреты: winscp_script.txt и DEPLOY_INSTRUCTIONS.md содержали SFTP-пароль в истории (известно, ротация не проводилась). В новые файлы пароли НЕ записывать.
• Yandex.Disk НЕ должен синхронизировать .git (ломал репозиторий на Windows).