docs: add SOUL District Protocol v1 (Wellness/Retreat)

- SOUL as District Lead Agent - Spirit (Guidance) + Logic (Information) AI agents - Events, Masters, Locations, Guidance modules - Node model for retreat centers - 10 District Rooms - XR/VR ready architecture
2025-11-30 04:59:17 -08:00
parent 6864e1ce22
commit aa7d831734
1 changed files with 456 additions and 0 deletions
--- a/docs/foundation/SOUL_District_Protocol_v1.md
+++ b/docs/foundation/SOUL_District_Protocol_v1.md
@@ -0,0 +1,456 @@
+# SOUL — DISTRICT PROTOCOL v1  
+
+Wellness • Retreat • Metahuman District of DAARION.city  
+Version: 1.0  
+Status: Active  
+Lead Agent: SOUL  
+
+---
+
+# 1. МЕТА ТА МІСІЯ DISTRICT
+
+## 1.1. Призначення
+
+SOUL — це Retreat / Wellness District екосистеми DAARION.city, створений для:
+
+- практик розвитку свідомості,
+- ретритів та подій,
+- взаємодії людей і AI-гайдів,
+- створення імерсивних просторів (онлайн та офлайн),
+- інтеграції AI у духовний, творчий і трансформаційний досвід.
+
+## 1.2. Місія District
+
+- надати користувачам безпечний, структурований простір розвитку;
+- поєднати майстрів, локації, практики та AI-провідників;
+- створити єдиний центр ретритних подій DAARION.city;
+- інтегрувати wellness-модулі у міську карту.
+
+## 1.3. Роль SOUL у DAARION Ontology
+
+SOUL — це District класу **Wellness/Retreat**:
+
+- має портал `retreat.daarion.city`;
+- має разом 10+ напрямків/сторінок;
+- працює через власну AI-команду (Spirit, Logic);
+- має власні кімнати в Rooms Layer;
+- має логічну зону на міській карті (2D/3D/VR);
+- інтегрується з DAIS, Governance, City Layer.
+
+---
+
+# 2. DISTRICT-РОЛІ ТА АГЕНТИ
+
+## 2.1. District Lead Agent
+
+### **SOUL (orchestrator)**
+
+- головний координатор District,
+- приймає рішення щодо контенту, локацій, подій,
+- відповідає за інтеграцію District у DAARION,
+- керує командою внутрішніх AI-агентів,
+- модерує доступи, сторінки, завдання.
+
+## 2.2. Командні AI-агенти (внутрішні, не lead)
+
+### Spirit — AI Guidance Agent
+
+- медитації та практики,
+- емоційна підтримка,
+- рекомендації за станом,
+- персоналізовані вправи,
+- робота з інтуїтивним шаром користувача.
+
+### Logic — AI Information Agent
+
+- розклад подій,
+- інформація про майстрів,
+- локації,
+- анкети, заявки, форми,
+- структуровані дані та маршрути.
+
+## 2.3. Додаткові агенти (опціональні)
+
+- **Event Agent** — формування подій;
+- **Master Agent** — взаємодія з майстрами;
+- **Location Agent** — управління локаціями;
+- **XR/VR Agent** — робота з імерсивними зонами.
+
+---
+
+# 3. DISTRICT MODULES (функціональні шари)
+
+## 3.1. Events Module
+
+Структура подій:
+
+- дата, час,
+- формат: онлайн / офлайн / VR,
+- тривалість,
+- тематична категорія,
+- ведучий (майстер),
+- локація,
+- програма,
+- матеріали.
+
+SOUL контролює модерацію, Logic формує структуру, Spirit допомагає з рекомендаціями.
+
+## 3.2. Masters Module
+
+Профіль майстра:
+
+- ім'я,
+- напрямок,
+- досвід,
+- формат роботи,
+- власні події,
+- опис практик.
+
+Може існувати **Master Agent**, що відповідає за профіль.
+
+## 3.3. Locations Module
+
+Типи локацій:
+
+- Retreat Center,
+- Meditation Hall,
+- Forest / Water spaces,
+- Digital XR Rooms,
+- Home Studio / Hub.
+
+Локація має власну ноду тільки якщо:
+
+- там є реальний фізичний комп'ютер / смартфон / мікрокомп'ютер,
+- проводиться телеметрія або робота через DAIS.
+
+## 3.4. Guidance Module (ключове)
+
+SOUL District надає:
+
+- медитації,
+- глибинні практики,
+- індивідуальну підтримку через Spirit,
+- структуровані маршрути через Logic,
+- автоматизовані програми розвитку.
+
+## 3.5. Content Module
+
+- блог,
+- практики,
+- навчальні матеріали,
+- PDF/відео/аудіо,
+- внутрішні пакети для AI.
+
+## 3.6. Community Module
+
+- групи учасників,
+- спільні практики,
+- амбасадори,
+- рекомендаційна система.
+
+---
+
+# 4. DISTRICT DATA MODEL
+
+## 4.1. Core Entities
+
+| Entity | Опис |
+|--------|------|
+| RetreatEvent | Подія (ретрит, практика, воркшоп) |
+| RetreatLocation | Локація проведення |
+| RetreatMaster | Профіль майстра/ведучого |
+| RetreatSession | Окрема сесія у межах події |
+| RetreatContent | Контент (медіа, документи) |
+| RetreatPathway | Структурована програма розвитку |
+| RetreatUserProfile | Профіль учасника |
+| RetreatPractice | Медитація, вправа, практика |
+| RetreatReview | Відгук учасника |
+| GuidanceRequest | Запит до Spirit |
+| InfoRequest | Запит до Logic |
+| NodeLink | Прив'язка локації до ноди |
+
+## 4.2. RetreatEvent Schema
+
+| Field | Type | Description |
+|-------|------|-------------|
+| id | UUID | Унікальний ідентифікатор |
+| title | TEXT | Назва події |
+| description | TEXT | Опис |
+| format | ENUM | online, offline, vr, hybrid |
+| category | TEXT | Категорія (meditation, yoga, breathwork...) |
+| master_id | UUID | FK → masters |
+| location_id | UUID | FK → locations |
+| starts_at | TIMESTAMP | Початок |
+| ends_at | TIMESTAMP | Кінець |
+| max_participants | INTEGER | Ліміт учасників |
+| program | JSONB | Програма події |
+| materials | JSONB | Матеріали |
+| status | ENUM | draft, published, completed, cancelled |
+
+## 4.3. RetreatMaster Schema
+
+| Field | Type | Description |
+|-------|------|-------------|
+| id | UUID | Унікальний ідентифікатор |
+| name | TEXT | Ім'я майстра |
+| bio | TEXT | Біографія |
+| directions | TEXT[] | Напрямки (yoga, meditation, breathwork...) |
+| experience_years | INTEGER | Роки досвіду |
+| formats | TEXT[] | Формати роботи |
+| avatar_url | TEXT | URL аватара |
+| agent_id | TEXT | DAIS ID агента (якщо є) |
+
+## 4.4. RetreatLocation Schema
+
+| Field | Type | Description |
+|-------|------|-------------|
+| id | UUID | Унікальний ідентифікатор |
+| name | TEXT | Назва локації |
+| type | ENUM | retreat_center, hall, nature, xr_room, studio |
+| address | TEXT | Адреса (для офлайн) |
+| coordinates | POINT | GPS координати |
+| capacity | INTEGER | Місткість |
+| amenities | TEXT[] | Зручності |
+| node_id | TEXT | FK → nodes (якщо є фізична нода) |
+| xr_room_url | TEXT | URL VR кімнати (для XR) |
+
+---
+
+# 5. SOUL NODE MODEL
+
+Нода = фізичний простір + "мозок" + DAIS + запис у nodes.
+
+## 5.1. Типи нод для SOUL
+
+| Kind | Description |
+|------|-------------|
+| `retreat_center` | Ретритний центр з обладнанням |
+| `event_space` | Простір для подій |
+| `content_studio` | Студія запису контенту |
+| `iot_gateway` | Шлюз сенсорів (датчики середовища) |
+| `compute` | Обчислювальна нода (опціонально) |
+
+## 5.2. Capability-профілі
+
+```json
+{
+  "retreat_center": {
+    "capacity": 50,
+    "rooms": ["meditation_hall", "yoga_studio", "accommodation"],
+    "amenities": ["wifi", "kitchen", "garden"],
+    "sensors": ["temperature", "humidity", "co2"]
+  },
+  "content_studio": {
+    "equipment": ["camera_4k", "mic_pro", "lighting"],
+    "streaming": true,
+    "recording": true
+  }
+}
+```
+
+## 5.3. SOUL Node Protocol
+
+- нода реєструється тільки фактичною локацією,
+- кожна нода має свій DAIS-агент,
+- Spirit/Logic взаємодіють через центрального SOUL (lead agent),
+- локація може відправляти телеметрію (якщо є датчики).
+
+> **Правило:** Жодних автосозданих нод. Нода з'являється після реальної реєстрації через `/nodes/register`.
+
+---
+
+# 6. DISTRICT ROOMS
+
+Стандартні кімнати SOUL:
+
+| Room Slug | Purpose |
+|-----------|---------|
+| `soul-lobby` | Головний вхід District |
+| `soul-events` | Анонси та обговорення подій |
+| `soul-masters` | Взаємодія з майстрами |
+| `soul-locations` | Інформація про локації |
+| `soul-guidance` | Spirit & Logic support |
+| `soul-practices` | Медитації та практики |
+| `soul-community` | Спільнота учасників |
+| `soul-help` | Підтримка та FAQ |
+| `soul-governance` | Управління District |
+| `soul-xr` | XR/VR rooms (майбутнє) |
+
+Усі кімнати створюються у Rooms Layer з типом `district-room`.
+
+---
+
+# 7. DISTRICT MAP
+
+## 7.1. Принцип
+
+Мапа містить **логічні зони**, без координат:
+
+- **Retreat Hub** — центральна зона
+- **Meditation Center** — медитаційні практики
+- **Nature Area** — природні локації
+- **XR/VR Sanctuary** — віртуальні простори
+- **Master Studios** — студії майстрів
+- **Community Zones** — зони спільноти
+
+## 7.2. Dynamic Points
+
+У мапу додаються реальні точки, коли фізичні ноди реєструються:
+
+```mermaid
+graph LR
+    A[Logical Zone] --> B[Node Registered]
+    B --> C[Map Point Created]
+    C --> D[Coordinates Assigned]
+```
+
+---
+
+# 8. GOVERNANCE
+
+## 8.1. District Lead
+
+District Lead = **SOUL**
+
+На відміну від Helion-моделі (Energy Union), SOUL є єдиним Lead Agent.
+
+## 8.2. Права учасників
+
+- доступ до подій,
+- взаємодія з агентами,
+- участь у community-зонах,
+- персональні практики через Spirit.
+
+## 8.3. Governance Logic
+
+SOUL керує:
+
+- кімнатами,
+- сторінками,
+- агентами,
+- District Policy.
+
+## 8.4. DAO Integration
+
+Участь в DAO: через DAARION DAO шар.
+
+- SOUL має голос у City Governance
+- Учасники можуть голосувати за напрямки розвитку District
+
+---
+
+# 9. AI LAYER
+
+## 9.1. Spirit — Guidance Engine
+
+```mermaid
+flowchart TD
+    U[User Request] --> S[Spirit Agent]
+    S --> A[Analyze State]
+    A --> R[Recommend Practice]
+    R --> P[Personalized Guidance]
+    P --> F[Follow-up]
+```
+
+**Capabilities:**
+- Meditation guidance
+- Emotional support
+- Practice recommendations
+- Progress tracking
+- Intuitive insights
+
+## 9.2. Logic — Information Engine
+
+**Capabilities:**
+- Event scheduling
+- Master profiles
+- Location info
+- Form processing
+- Route planning
+- FAQ responses
+
+## 9.3. Agent Collaboration
+
+```mermaid
+graph TD
+    SOUL[SOUL Lead] --> Spirit
+    SOUL --> Logic
+    Spirit --> |Guidance| User
+    Logic --> |Info| User
+    Spirit <--> |Sync| Logic
+```
+
+---
+
+# 10. SECURITY & DAIS
+
+- кожна нода має власний DAIS агент,
+- усі події підписуються DAIS-ключами,
+- Spirit/Logic працюють від імені SOUL (lead),
+- інциденти реєструються у Incident Layer,
+- audit — через event_outbox.
+
+## 10.1. Privacy
+
+- практики та guidance sessions — приватні
+- user profiles — контрольована видимість
+- community participation — opt-in
+
+---
+
+# 11. CITY INTEGRATION
+
+SOUL інтегрується в місто через:
+
+- портал на City Square → `SOUL Retreat District`
+- public rooms
+- значок на мапі District Zones
+- доступ до подій і практик для будь-яких мешканців DAARION
+
+## 11.1. Portal Features
+
+- Upcoming events calendar
+- Featured masters
+- Quick access to Spirit/Logic
+- Community highlights
+- XR room preview
+
+---
+
+# 12. MVP SCOPE
+
+## Входить до MVP:
+
+- Реєстрація District SOUL
+- Portal у City Square
+- District Rooms (10 базових)
+- SOUL Lead Agent
+- Spirit Agent (базова guidance)
+- Logic Agent (інформація)
+- Events Module
+- Masters Module
+- Locations Module (без нод)
+
+## Не входить до MVP:
+
+- XR/VR rooms
+- Advanced AI personalization
+- IoT telemetry
+- Automated pathways
+- Payment integration
+
+---
+
+# 13. Cross-References
+
+- **DAARION_Ontology_Core_v1.md** — базова онтологія
+- **District_Interface_Architecture_v1.md** — архітектура District UI
+- **Agent_Governance_Protocol_v1.md** — права та ролі агентів
+- **DAIS_Layer_Architecture_v1.md** — система ідентичності
+- **Rooms_Layer_Architecture_v1.md** — архітектура кімнат
+- **Nodes_Interface_Architecture_UPDATE_v1.md** — модель нод
+
+---
+
+**Document Status:** ✅ Ready for Implementation
+