Skip to content

# 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: `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/`.

## Приклади

### Правильно

    # Оновлення токеноміки
    - Редагуємо `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