chore: organize documentation structure for monorepo

- Create /docs structure (microdao, daarion, agents) - Organize 61 cursor technical docs - Add README files for each category - Copy key documents to public categories - Add GitHub setup instructions and scripts
2025-11-15 04:08:35 -08:00
parent 5520665600
commit c552199eed
138 changed files with 39624 additions and 40 deletions
--- a/docs/CONTRIBUTING_DOCS.md
+++ b/docs/CONTRIBUTING_DOCS.md
@@ -0,0 +1,141 @@
+# Contributing to Documentation
+
+Правила роботи з документацією проєкту MicroDAO / DAARION.city.
+
+---
+
+## Документація: джерела правди
+
+### Токеноміка
+
+- **Актуальна токеноміка міста:** `docs/tokenomics/city-tokenomics.md`
+- Усі файли з токеноміки в `docs/_archive/` є застарілими і використовуються лише як історичні чернетки.
+- При будь-яких змінах токеноміки редагуємо тільки `city-tokenomics.md` і оновлюємо версію у frontmatter.
+
+### Архітектура
+
+- **Основна архітектура:** `docs/cursor/02_architecture_basics.md`
+- **Внутрішні сервіси:** `docs/cursor/34_internal_services_architecture.md`
+- **Service Mesh:** `docs/cursor/35_microdao_service_mesh_design.md`
+
+### API
+
+- **API контракти:** `docs/cursor/03_api_core_snapshot.md`
+
+### Агенти
+
+- **Agent Runtime Core:** `docs/cursor/12_agent_runtime_core.md`
+- **Agent Memory System:** `docs/cursor/13_agent_memory_system.md`
+- **Private Agents Lifecycle:** `docs/cursor/38_private_agents_lifecycle_and_management.md`
+
+### Інтеграція
+
+- **DAARION.city Integration:** `docs/cursor/DAARION_city_integration.md`
+- **Website Integration:** `docs/cursor/50_daarion_city_website_integration.md`
+- **Integration Guide:** `docs/integration-daarion.md`
+
+---
+
+## Правила версіонування
+
+### Канонічні документи
+
+Канонічні документи мають frontmatter з версією:
+
+```yaml
+---
+title: Document Title
+version: 1.0.0
+status: canonical
+last_updated: 2024-11-14
+---
+```
+
+### Оновлення документів
+
+1. Редагуєш **той самий** файл (не створюєш новий).
+2. Змінюєш версію й дату у frontmatter:
+   ```yaml
+   version: 1.1.0
+   last_updated: 2024-12-01
+   ```
+3. Додаєш запис у секцію Changelog внизу документа.
+
+### Legacy документи
+
+- Старі версії документів переносяться в `docs/_archive/`.
+- На початку legacy файлу додається помітка:
+  ```markdown
+  > **LEGACY:** Цей документ застарів. Актуальна версія: `docs/path/to/canonical.md`.
+  ```
+
+---
+
+## Структура документації
+
+```
+docs/
+├── cursor/              # Детальні технічні специфікації
+├── tokenomics/          # Токеноміка (канонічний: city-tokenomics.md)
+├── _archive/            # Застарілі документи
+├── integration-daarion.md  # Консолідований гайд інтеграції
+├── CONTRIBUTING_DOCS.md   # Цей файл
+└── README.md            # Загальний огляд документації
+```
+
+---
+
+## Як працювати з Cursor
+
+### При створенні промптів
+
+Завжди вказуй канонічні документи:
+
+> Використовуй `docs/tokenomics/city-tokenomics.md` як єдине актуальне джерело токеноміки.
+
+> Використовуй `docs/cursor/50_daarion_city_website_integration.md` для інтеграції з сайтом.
+
+### При оновленні документації
+
+1. Знайди канонічний документ (перевір frontmatter на `status: canonical`).
+2. Онови версію у frontmatter.
+3. Додай запис у Changelog.
+4. Якщо є legacy версії — перенеси їх в `_archive/`.
+
+---
+
+## Приклади
+
+### Правильно
+
+```markdown
+# Оновлення токеноміки
+- Редагуємо `docs/tokenomics/city-tokenomics.md`
+- Оновлюємо версію: 1.0.0 → 1.1.0
+- Додаємо запис у Changelog
+```
+
+### Неправильно
+
+```markdown
+# Створення нового файлу
+- ❌ НЕ створюємо `city-tokenomics-v2.md`
+- ❌ НЕ створюємо `city-tokenomics-updated.md`
+- ✅ Редагуємо існуючий `city-tokenomics.md`
+```
+
+---
+
+## Питання?
+
+Якщо не впевнений, який документ є канонічним:
+
+1. Перевір frontmatter на `status: canonical`.
+2. Перевір `docs/README.md` — там вказані канонічні документи.
+3. Перевір `docs/CONTRIBUTING_DOCS.md` (цей файл).
+
+---
+
+**Останнє оновлення:** 2024-11-14
+
+