Baseline md2vk: docs, audit log, docker 8420, openspec, deploy

docs/index.md

@@ -0,0 +1,65 @@
+# md2vk — Документация
+
+Указатель документации проекта. Все реквизиты и доступы — в [access.md](access.md).
+
+## Разделы
+
+| Файл | Содержание |
+|------|------------|
+| [index.md](index.md) | Этот указатель, обзор проекта |
+| [access.md](access.md) | **Все реквизиты и доступы к смежным сервисам** (vps02, Caddy, gitverse, gitea, DNS, VK API, fail2ban) |
+| [architecture.md](architecture.md) | Архитектура, компоненты, порты, схема |
+| [vk-api.md](vk-api.md) | Порядок взаимодействия с VK API: OAuth-флоу, wall.post, format_data, ограничения (лонгриды) |
+| [security.md](security.md) | Безопасность: пароль, basic auth, блокировка после 5 попыток, Fernet, API-ключ |
+| [deploy.md](deploy.md) | Деплой: docker на bigbox, Caddy на vps02, fail2ban |
+| [status.md](status.md) | Статус реализации по фазам (в т.ч. история) |
+
+## Обзор
+
+Сервис публикации Markdown-текста на стене VK через официальный VK API (`wall.post`).
+
+```
+┌─────────────┐     ┌─────────────┐     ┌──────────────┐
+│  Hermes     │────▶│  md2vk      │────▶│  VK API      │
+│  Agent      │     │  :8420      │     │  wall.post   │
+│  (skill)    │◀────│  FastAPI    │     │  vk.com      │
+└─────────────┘     └─────────────┘     └──────────────┘
+```
+
+- Публикация Markdown → VK wall.post с `format_data` (жирный, курсив, код, ссылки, заголовки, цитаты)
+- Конвертация Markdown → VK format_data без публикации (preview)
+- Управление VK-аккаунтами (несколько страниц), шифрование токенов (Fernet)
+- Архив публикаций с фильтрацией по статусу
+- Отложенные посты (статус `scheduled`; планировщик — открытая задача)
+
+## Внешние точки
+
+| Что | Адрес |
+|-----|-------|
+| Прод | https://md2vk.nixg.ru (basic auth, см. [security.md](security.md)) |
+| Swagger | https://md2vk.nixg.ru/docs (за basic auth) |
+| Локально | http://127.0.0.1:8420 (bigbox), Swagger http://127.0.0.1:8420/docs |
+
+## Быстрый старт (dev)
+
+```bash
+cd /opt/md2vk
+source venv/bin/activate
+pip install -r requirements.txt
+# ключ шифрования уже есть: secrets/token_encryption_key (не в git)
+make dev   # uvicorn :8000 --reload (для dev; прод-порт 8420 в docker)
+```
+
+## Git
+
+Схема: **gitverse.ru (истина) → gitea.nixg.ru (pull mirror)**. Подробности в [access.md](access.md).
+
+## Открытые задачи (см. [status.md](status.md) и openspec/)
+
+- Планировщик отложенных постов (worker + cron)
+- Web UI (форма поста + превью), сейчас только API
+- OAuth-флоу VK VK ID (кнопка «Прикрепить аккаунт») — сейчас токен вводится вручную
+- Unit/integration тесты (pytest)
+- Rate limiting (in-memory bucket)
+- Retry при сетевых ошибках VK API
+- Read-only rootfs в Docker (частично: `read_only: true` в compose)