From 8123051ca75b8257dea487bdc0acbb1de5e0926c Mon Sep 17 00:00:00 2001 From: Storozhenko Evgeny Date: Sat, 12 Sep 2026 17:15:10 +0000 Subject: [PATCH] =?UTF-8?q?docs(project):=20=D1=84=D0=B0=D0=B9=D0=BB=D1=8B?= =?UTF-8?q?=20=D0=BF=D1=80=D0=BE=D0=B5=D0=BA=D1=82=D0=B0=20=D0=B2=20docs/?= =?UTF-8?q?=20(STATUS,=20PRD,=20TODO,=20WALKTHROUGH)=20+=20AGENTS.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 4 ++++ docs/PRD.md | 35 +++++++++++++++++++++++++++++++++++ docs/STATUS.md | 37 +++++++++++++++++++++++++++++++++++++ docs/TODO.md | 13 +++++++++++++ docs/WALKTHROUGH.md | 39 +++++++++++++++++++++++++++++++++++++++ 5 files changed, 128 insertions(+) create mode 100644 docs/PRD.md create mode 100644 docs/STATUS.md create mode 100644 docs/TODO.md create mode 100644 docs/WALKTHROUGH.md diff --git a/AGENTS.md b/AGENTS.md index dcd1ee2..3066ccb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,6 +14,10 @@ Никакой подробной документации и истории изменений в README не держим. - `docs/` — вся подробная документация проекта: инструкции, справочники, дорожные карты, заметки об опыте настройки. +- **Файлы проекта (статус/требования/задачи/журнал) — тоже в `docs/`:** + `docs/STATUS.md` (текущее состояние), `docs/PRD.md` (требования), + `docs/TODO.md` (журнал задач), `docs/WALKTHROUGH.md` (капитанский журнал). + При закрытии сессии обновляются именно они. - `AGENTS.md` — правила работы для агентов (этот файл). - Подробная эксплуатационная документация НЕ должна лежать в корне репозитория. Новые документы создавать только в `docs/`. diff --git a/docs/PRD.md b/docs/PRD.md new file mode 100644 index 0000000..01e9ccf --- /dev/null +++ b/docs/PRD.md @@ -0,0 +1,35 @@ +# dedinit.ru — PRD (требования к проекту) + +## Цель +Личный технический блог dedinit.ru на Hugo: быстрая публикация статей (MLOps/DevOps/Linux/CI-CD, личный опыт) без поломки сайта. + +## Пользователи +- Автор (владелец) — публикует контент, настраивает тему. +- Читатели — русскоязычная аудитория (ru-ru), потребляют статьи. + +## Функциональные требования +- Генерация статического сайта Hugo Extended, тема rDedInit (форк PaperMod). +- Статьи — bundle: `content/posts//index.md` + hero.svg (viewBox 1200x400, фон #0a0c10, заголовок #58a6ff). +- `date`/`lastmod` — в прошлом (иначе Hugo не публикует); `draft: false`. +- Подсветка блочного кода (цель проекта). +- RSS с полным текстом (site.Params.ShowFullTextinRSS, лимит 5 постов). +- Деплой — ТОЛЬКО `make deploy` (SFTP paramiko на kpa39l.myjino.ru:2222; аккаунт SFTP-only, rsync/ssh-exec невозможны). +- Русскоязычный UI (задача локализации i18n в процессе). + +## Нефункциональные требования +- Git-история сохраняется (без потерь; git mv). +- Секреты/пароли в коммиты НЕ добавлять. +- Документация — на русском, в docs/; README — краткое введение. +- Все изменения проекта — через OpenSpec (propose → design → apply → archive). +- Не удалять/не перезаписывать данные пользователя без явного подтверждения. + +## Границы (что НЕ делаем) +- Не внедряем мультиязычность en/ru (пока). +- Не переводим контент постов — только UI. +- Не меняем провайдер хостинга/деплоя без запроса. + +## Критерии готовности +- Сайт собирается (`make build`) и деплоится (`make deploy`) без ошибок. +- UI на русском (по завершении локализации). +- Репозиторий: чистый git-статус, все коммиты в gitverse. +- Изменения проходят OpenSpec-цикл и архивируются. \ No newline at end of file diff --git a/docs/STATUS.md b/docs/STATUS.md new file mode 100644 index 0000000..e5d6770 --- /dev/null +++ b/docs/STATUS.md @@ -0,0 +1,37 @@ +# dedinit.ru — Статус + +Обновлено: 2026-09-12 (сессия уборки структуры и OpenSpec) + +## Текущее состояние +Сайт-блог dedinit.ru на Hugo Extended (тема rDedInit/форк PaperMod) в порядке: структура репозитория приведена к стандарту (README краткий + вся документация в docs/ + AGENTS.md), всё запушено в gitverse (main). Рабочее дерево чистое. Следующая задача (локализация UI) оформлена через OpenSpec, реализация не начата. + +## Сделано +- 2026-09-12: Уборка структуры репозитория — вся документация перенесена в docs/ (git mv, история сохранена), README.md переписан кратко, создан AGENTS.md с правилами проекта. +- 2026-09-12: Правило «ВСЕ изменения проекта — через OpenSpec» добавлено в AGENTS.md (commit 0f4d6da). +- 2026-09-12: Задача «Русская локализация i18n/ru.toml» оформлена через OpenSpec (propose) — change `localize-i18n-ru` валиден, запушен (f07bffe). Артефакты: proposal.md, specs/i18n/spec.md, design.md, tasks.md. +- 2026-09-12: В локальные openspec-скиллы проекта (.hermes/skills/) добавлена секция «Проверка (validate) — ПРАВИЛЬНЫЙ синтаксис» во все 6 SKILL.md (правильный вызов: `openspec validate <имя>`, НЕ `--change`). + +## В работе / Следующие шаги +- [ ] **Реализация локализации i18n/ru.toml** (openspec change `localize-i18n-ru`, стадия apply): создать `i18n/ru.toml` с русскими переводами ключей темы, `make build`, проверить grep'ами в public/, закоммитить и запушить. +- [ ] Затем (из ROADMAP): цветовая схема под бренд dedinit(), русские переводы i18n, Telegram-посты (layout + карточки + shortcode), навигация, SEO и др. + +## Как запустить / проверить +```bash +cd /opt/dedinit.ru +make build # сборка (hugo --minify) +make deploy-dry-run # симуляция деплоя +make deploy # ЕДИНСТВЕННЫЙ способ деплоя (SFTP, требует SSHPASS) +openspec validate localize-i18n-ru # валидация active-change +``` +Источник истины — gitverse (origin main, SSH). + +## Ключевые артефакты +- `/opt/dedinit.ru/AGENTS.md` — правила работы агентов (русский, docs/, make deploy, OpenSpec) +- `/opt/dedinit.ru/README.md` — краткое введение +- `/opt/dedinit.ru/docs/` — вся подробная документация (DEPLOY_INSTRUCTIONS, ROADMAP, PAPERMOD_PARAMS, QWEN, gitea-setup, ssh_setup, Telegram_frontend, local-aux-models, favicon-logo-setup, archive/) +- `/opt/dedinit.ru/openspec/changes/localize-i18n-ru/` — активный change (propose готов, apply впереди) +- `/opt/dedinit.ru/.hermes/skills/openspec-*/SKILL.md` — openspec-скиллы проекта (с секцией про validate) + +## Открытые вопросы +- Продолжать ли локализацию (apply change localize-i18n-ru) в следующей сессии? (пользователь ещё не подтвердил apply) +- Перенести ли секцию про validate в глобальный скилл Hermes (переживёт перезапись локальных openspec-скиллов)? \ No newline at end of file diff --git a/docs/TODO.md b/docs/TODO.md new file mode 100644 index 0000000..26717d0 --- /dev/null +++ b/docs/TODO.md @@ -0,0 +1,13 @@ +# TODO — dedinit.ru + +Формат: | дата | задача | статус | закрыта в | +|---|---|---|---| +| 2026-09-12 | Уборка структуры: вся документация в docs/, краткий README, AGENTS.md | ✅ закрыта | session уборки (коммит d426aa3) | +| 2026-09-12 | Правило «ВСЕ изменения через OpenSpec» в AGENTS.md | ✅ закрыта | commit 0f4d6da | +| 2026-09-12 | Оформить задачу локализации i18n/ru.toml через OpenSpec (propose) | ✅ закрыта | commit f07bffe (change localize-i18n-ru) | +| 2026-09-12 | Добавить в openspec-скиллы правильный синтаксис validate | ✅ закрыта | .hermes/skills/openspec-*/SKILL.md | +| 2026-09-12 | Файлы проекта (STATUS/PRD/TODO/WALKTHROUGH) — в docs/ | ✅ закрыта | docs/STATUS.md, docs/PRD.md, docs/TODO.md, docs/WALKTHROUGH.md | +| 2026-09-12 | Реализовать локализацию i18n/ru.toml (apply change localize-i18n-ru) | 🔵 открыта | | +| — | Настроить цветовую схему под бренд dedinit() | 🔵 открыта | (ROADMAP) | +| — | Русские переводы i18n (Read more→Читать далее и др.) | 🔵 открыта | (ROADMAP) | +| — | Telegram-посты: layout + карточки + shortcode | 🔵 открыта | (ROADMAP) | \ No newline at end of file diff --git a/docs/WALKTHROUGH.md b/docs/WALKTHROUGH.md new file mode 100644 index 0000000..d8ce885 --- /dev/null +++ b/docs/WALKTHROUGH.md @@ -0,0 +1,39 @@ +# 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 ` — ОШИБКА (`unknown option '--change'`). Правильно: `openspec validate `. Это зафиксировано во всех 6 локальных openspec-скиллах (.hermes/skills/openspec-*/SKILL.md). + +### Файлы проекта +- Согласно правилу «вся документация в docs/» — файлы проекта лежат в docs/: + - `docs/STATUS.md` — текущее состояние, сделано, следующие шаги, как проверить. + - `docs/PRD.md` — требования, границы, критерии готовности. + - `docs/TODO.md` — журнал задач (история, статусы). + - `docs/WALKTHROUGH.md` — этот журнал. + +### Как повторить / проверить +```bash +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). \ No newline at end of file