microdao-daarion/docs/CONTRIBUTING_DOCS.md

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 з версією:

---
title: Document Title
version: 1.0.0
status: canonical
last_updated: 2024-11-14
---

Оновлення документів

1. Редагуєш той самий файл (не створюєш новий).
2. Змінюєш версію й дату у frontmatter:

   version: 1.1.0
   last_updated: 2024-12-01
   

3. Додаєш запис у секцію Changelog внизу документа.

Legacy документи

• Старі версії документів переносяться в docs/_archive/.
• На початку legacy файлу додається помітка:

  > **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/.

---

Приклади

Правильно

# Оновлення токеноміки
- Редагуємо `docs/tokenomics/city-tokenomics.md`
- Оновлюємо версію: 1.0.0 → 1.1.0
- Додаємо запис у Changelog

Неправильно

# Створення нового файлу
- ❌ НЕ створюємо `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