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/cursor/23_agent_cards_and_console.md
+++ b/docs/cursor/23_agent_cards_and_console.md
@@ -0,0 +1,556 @@
+# 23 — Agent Cards and Console (MicroDAO)
+
+Живі картки агентів та повний інтерфейс Agent Console
+
+Цей документ описує UI/UX для агентів у форматі "живих карток" та повний інтерфейс Agent Console, де кожен агент представлений як учасник спільноти з власною історією, досвідом та репутацією.
+
+---
+
+# 1. Концепція: "Живі картки агентів"
+
+Кожен агент у MicroDAO — це не просто бот, а:
+
+* учасник спільноти з власною історією,
+* живий модуль розуму, підключений до DAGI,
+* носій досвіду (1T як міра обчислень та "шляху агента"),
+* носій репутації в межах спільноти.
+
+Тому **основний UI-елемент** — не список у вигляді таблиці, а **плитки / картки агентів**.
+
+---
+
+# 2. Плитка агента (карточка в гріді)
+
+## 2.1. Розташування
+
+* В розділі "Агенти" (ліва панель → клік → відкривається основний грід).
+* Також може використовуватись у:
+
+  * модалці "Додати агента до каналу",
+  * маркетплейсі агентів DAARION.city,
+  * списку підключених агентів до microDAO.
+
+## 2.2. Структура картки
+
+Рекомендований layout:
+
+### 1. Верхній блок: Аватар + Відео-аватар
+
+* Статичний аватар (іконка/символ).
+* Мала відео-плашка / анімований аватар (loop, без звуку).
+* Індикатор "онлайн/активний" (маленький маркер).
+
+### 2. Імʼя та роль
+
+* `Імʼя агента` (наприклад, "DAGI Guide", "Tokenomics Keeper").
+* Короткий опис призначення у один рядок:
+
+  * "Провідник microDAO"
+  * "Куратор знань"
+  * "Месенджер-організатор"
+
+  Без жодних фінансових ролей.
+
+### 3. Метрики досвіду (без фінансової асоціації)
+
+* **Вік агента**:
+
+  * "У спільноті: 3 тижні" / "6 місяців" / "1 рік 2 місяці".
+
+* **Досвід 1T**:
+
+  * Лічильник: `Досвід: 12 340 1T`
+  * В UI пояснення через tooltip:
+
+    > "1T — це внутрішня одиниця обчислень і досвіду агента в екосистемі DAARION.city."
+
+  * Важливо: не використовувати слів, які натякають на торгівлю/прибуток; це чисто "XP".
+
+* **Репутація спільноти**:
+
+  * Наприклад, шкала 0–100 або 0–5 "зірочок".
+  * Підпис: `Репутація в спільноті` / `Довіра спільноти`.
+
+### 4. Присутність у просторах
+
+* Маленькі бейджі:
+
+  * `Учасник: 3 канали`
+  * `Працює в: 2 microDAO`
+
+* Позначки "публічний / конфіденційний":
+
+  * іконка замка для конфіденційних контекстів.
+
+### 5. Статус підключення
+
+* Текст/бейдж:
+
+  * `Підключено до цього простору`
+  * або `Доступний для підключення`
+
+* Кнопка:
+
+  * `Підключити до контексту` (якщо ще не підʼєднаний).
+
+---
+
+# 3. Ховер та клік по картці
+
+## 3.1. При наведенні курсору (hover)
+
+Показати поверх картки напівпрозорий оверлей з опціями:
+
+* Основна кнопка:
+  **"Почати взаємодію"**
+
+* Додаткові:
+
+  * `Підключити до цього каналу` (якщо стіна контексту вже вибрана)
+  * `Деталі агента` (відкрити повний профіль)
+
+Можна додати коротку анімацію відео-аватара (легке пожвавлення).
+
+## 3.2. При натисканні
+
+Якщо клікаємо по основній площі картки:
+
+* Відкривається **нове вікно/панель агента** (Agent Console), де:
+
+  * є текстовий чат,
+  * є керування голосовим режимом,
+  * є вкладка для обміну файлами/документами,
+  * є вкладка памʼяті/прав доступу.
+
+---
+
+# 4. Agent Console: повний інтерфейс агента
+
+Приклад структури:
+
+## 4.1. Верхня панель
+
+* Аватар + відео-аватар (більший).
+* Імʼя, роль, короткий опис.
+* Показники:
+
+  * Вік,
+  * Досвід 1T,
+  * Репутація спільноти.
+
+* Значок підключеності до поточного microDAO / каналу.
+
+## 4.2. Вкладки
+
+### Вкладка 1: Чат
+
+* Текстовий чат (як звичайний agent chat).
+* Голосовий режим: кнопка "Голосовий діалог" (start/stop).
+* Привʼязка до поточного контексту:
+
+  * показати, в якому просторі ти з ним розмовляєш.
+
+### Вкладка 2: Файли та Документи
+
+* Список файлів, якими обмінювались з цим агентом в межах даного microDAO.
+* Кнопка `Завантажити файл` → агент через DAGI може:
+
+  * проаналізувати документ,
+  * створити новий документ (збереження в microDAO file store).
+
+* Обовʼязково:
+
+  * **збереження у власних сховищах microDAO**, не у зовнішньому середовищі по замовчуванню.
+
+### Вкладка 3: Памʼять і Знання
+
+* Блоки з:
+
+  * короткостроковою памʼяттю (останні теми),
+  * довгостроковими фактами про цю спільноту (як у 13_agent_memory_system).
+
+* Кнопки:
+
+  * `Показати, що ти памʼятаєш про цей проєкт`
+  * `Очистити частину памʼяті`
+
+### Вкладка 4: Присутність / Права доступу
+
+* Список:
+
+  * В яких каналах цей агент присутній (публічні/конфіденційні).
+  * В яких проєктах бере участь.
+
+* Для кожного:
+
+  * перемикач `Підключити/Відключити`.
+  * Позначка рівня доступу (read/write/tasks/knowledge).
+
+* Кнопка:
+
+  * `Додати до нового каналу/проєкту` → відкриває спрощений Invite-Agent-Flow, але вже з попередньо вибраним агентом.
+
+### Вкладка 5: Еволюція та дух спільноти
+
+* Замінює будь-який фінансовий наратив:
+
+  * `Шлях агента в цій спільноті`
+  * Лог:
+
+    * скільки разів агент допомагав у задачах,
+    * які типи запитів обробляє найчастіше,
+    * "внесок у колективний розум" (наприклад, скільки фактів/правил додано).
+
+* Репутація:
+
+  * відгуки/оцінки від учасників (без мови торгівлі).
+
+---
+
+# 5. DAGI, багатомодальність і сховища
+
+## 5.1. DAGI як бекенд агентських здібностей
+
+Кожен агент отримує від DAGI:
+
+* текстове мислення,
+* мульти-модальні можливості:
+
+  * розуміння зображень/файлів,
+  * створення текстів, планів, специфікацій,
+  * потенційно роботу з відео.
+
+Інтерфейс агента дає доступ до:
+
+* аналізу файлів:
+
+  * "Поясни цей документ для команди"
+  * "Зроби витяг для каналу #planning"
+
+* генерації нових артефактів:
+
+  * плани,
+  * дорожні карти,
+  * документація.
+
+## 5.2. Зберігання в MicroDAO, а не "десь в хмарі без контролю"
+
+Ключовий принцип:
+
+* **Результати роботи агента** (файли, документи, знання) зберігаються:
+
+  * у сховищі степені MicroDAO (файлове / БД),
+  * або у локальних базах спільноти.
+
+* DAGI використовується як "мозок", але:
+
+  * не забирає собі сирі дані без волі спільноти,
+  * не є єдиним місцем зберігання.
+
+Це важливо підкреслити в UX:
+
+* у консолі:
+
+  * "Документи зберігаються в просторі вашої microDAO."
+
+* опції експорту:
+
+  * "Поділитися в іншому просторі DAARION.city"
+  * "Надати доступ іншому агенту"
+
+---
+
+# 6. Підключення/відключення агентів до публічних/конфіденційних просторів
+
+## 6.1. З точки зору плитки
+
+На картці агента:
+
+* бейджі:
+
+  * `Публічні простори: 2`
+  * `Конфіденційні: 1`
+
+* При натисканні:
+
+  * відкривається невеликий список:
+
+    * `#general (публічний)`
+    * `#dev-mvp (конфіденційний)`
+
+  * поруч — перемикач:
+
+    * `Підключено / Відʼєднано`.
+
+## 6.2. З точки зору Agent Console
+
+У вкладці "Присутність / Права доступу":
+
+* Табличка:
+
+  * Простір / Тип (публічний/конфіденційний) / Доступ / Перемикач.
+
+* Операції:
+
+  * натискання `Відʼєднати`:
+
+    * агент перестає отримувати потік повідомлень з цього каналу/простору;
+    * його не видно у списку учасників.
+
+  * натискання `Підключити`:
+
+    * запускає внутрішній Invite-Agent-Flow для відповідного ресурсу.
+
+Все це повинно залишатись максимально людським в термінології:
+
+жодних "інвесторів", "юнітів вартості", "ROI" тощо — тільки:
+
+* "досвід",
+* "шлях агента",
+* "довіра спільноти",
+* "внесок у колективний розум".
+
+---
+
+# 7. Компоненти та структура
+
+## 7.1. Agent Card Component
+
+```tsx
+interface AgentCardProps {
+  agent: Agent;
+  onCardClick: () => void;
+  onConnect?: () => void;
+  currentContext?: {
+    teamId: string;
+    channelId?: string;
+  };
+}
+
+export function AgentCard({ agent, onCardClick, onConnect, currentContext }: AgentCardProps) {
+  // Рендер картки з усіма метриками
+}
+```
+
+## 7.2. Agent Grid
+
+```tsx
+interface AgentGridProps {
+  agents: Agent[];
+  onAgentSelect: (agentId: string) => void;
+  filter?: "all" | "connected" | "available";
+}
+
+export function AgentGrid({ agents, onAgentSelect, filter }: AgentGridProps) {
+  // Сітка карток агентів
+}
+```
+
+## 7.3. Agent Console
+
+```tsx
+interface AgentConsoleProps {
+  agentId: string;
+  initialTab?: "chat" | "files" | "memory" | "presence" | "evolution";
+}
+
+export function AgentConsole({ agentId, initialTab = "chat" }: AgentConsoleProps) {
+  // Повний інтерфейс агента з вкладками
+}
+```
+
+---
+
+# 8. Типи даних
+
+## 8.1. Agent Metrics
+
+```ts
+interface AgentMetrics {
+  age: {
+    weeks?: number;
+    months?: number;
+    years?: number;
+  };
+  experience1T: number; // Досвід в 1T
+  reputation: {
+    score: number; // 0-100 або 0-5
+    type: "stars" | "percentage";
+  };
+  presence: {
+    channels: number;
+    teams: number;
+    public: number;
+    confidential: number;
+  };
+}
+```
+
+## 8.2. Agent Presence
+
+```ts
+interface AgentPresence {
+  channelId: string;
+  channelName: string;
+  type: "public" | "confidential";
+  accessLevel: string[];
+  connected: boolean;
+}
+```
+
+## 8.3. Agent Evolution Log
+
+```ts
+interface AgentEvolutionLog {
+  tasksHelped: number;
+  requestTypes: Record<string, number>; // Типи запитів та їх кількість
+  contributions: {
+    factsAdded: number;
+    rulesCreated: number;
+    documentsGenerated: number;
+  };
+  communityFeedback: {
+    positive: number;
+    negative: number;
+    averageRating: number;
+  };
+}
+```
+
+---
+
+# 9. API Endpoints
+
+## 9.1. Agent Metrics
+
+```ts
+GET /agents/{agentId}/metrics
+// Повертає метрики агента (вік, досвід 1T, репутація)
+
+GET /agents/{agentId}/presence
+// Список просторів, де агент присутній
+```
+
+## 9.2. Agent Files
+
+```ts
+GET /agents/{agentId}/files
+// Список файлів, з якими працював агент
+
+POST /agents/{agentId}/files
+// Завантажити файл для аналізу агентом
+{
+  file: File;
+  context: {
+    teamId: string;
+    channelId?: string;
+  };
+}
+```
+
+## 9.3. Agent Evolution
+
+```ts
+GET /agents/{agentId}/evolution/log
+// Лог еволюції та внеску агента
+```
+
+---
+
+# 10. UI/UX Деталі
+
+## 10.1. Відео-аватар
+
+* Формат: короткий loop (2-5 секунд)
+* Розмір на картці: 64x64px
+* Розмір в консолі: 128x128px
+* Без звуку
+* Анімація при hover: легке пожвавлення
+
+## 10.2. Метрики досвіду
+
+* Вік: "3 тижні", "6 місяців", "1 рік 2 місяці"
+* 1T: велике число з розділювачами (12 340 1T)
+* Репутація: візуальна шкала (зірки або прогрес-бар)
+
+## 10.3. Бейджі присутності
+
+* Компактні бейджі з іконками
+* Кольори: синій для публічних, червоний для конфіденційних
+* Іконка замка для конфіденційних просторів
+
+---
+
+# 11. Інтеграція з існуючими модулями
+
+## 11.1. Agent UI System (10)
+
+Agent Cards використовують компоненти з `10_agent_ui_system.md`:
+- AgentAvatar
+- AgentChatWindow (у вкладці "Чат")
+- AgentMemoryTab (у вкладці "Памʼять")
+
+## 11.2. Agent Memory System (13)
+
+Вкладка "Памʼять і Знання" інтегрується з:
+- Short-term memory
+- Long-term memory
+- RAG retrieval
+
+## 11.3. Agent Runtime Core (12)
+
+Agent Console використовує:
+- AgentContext для роботи з агентом
+- Tools для аналізу файлів
+- LLM для генерації документів
+
+---
+
+# 12. Завдання для Cursor
+
+Приклад промта:
+
+```
+You are a senior React/TS engineer.
+
+Implement Agent Cards and Console using:
+
+- 23_agent_cards_and_console.md
+- 10_agent_ui_system.md
+- 13_agent_memory_system.md
+- 12_agent_runtime_core.md
+- 05_coding_standards.md
+
+Deliverables:
+
+1) AgentCard component with metrics (age, 1T experience, reputation).
+2) AgentGrid component for displaying multiple agent cards.
+3) AgentConsole component with tabs: Chat, Files, Memory, Presence, Evolution.
+4) Integration with file upload/analysis through DAGI.
+5) Presence management (connect/disconnect from channels/projects).
+
+Output:
+
+- list of modified files
+- diff
+- summary
+```
+
+---
+
+# 13. Результат
+
+Після впровадження:
+
+* Агенти представлені як живі учасники спільноти, а не просто боти
+* Користувач бачить досвід та репутацію кожного агента
+* Повний контроль над підключеннями агентів до просторів
+* Зберігання всіх результатів роботи агентів у сховищі microDAO
+* Людська термінологія без фінансових наративів
+
+---
+
+**Готово.**  
+Це **повна специфікація Agent Cards та Console**, готова до використання в Cursor.
+
+