microdao-daarion/docs/cursor/08_agent_first_onboarding.md

08 — Agent-First Onboarding Specification (MicroDAO)

Цей документ описує нову модель онбордингу MicroDAO:
користувач входить у чат з агентом-провідником, який крок за кроком створює спільноту, канал і налаштовує агента.

Весь процес — діалоговий.
Усі API-виклики — ті самі, що в 03_api_core_snapshot.md.

---

1. Мета

Замінити класичні форми/кроки онбордингу повністю агентським інтерфейсом.
Увесь onboarding виконується через AgentOnboardingChat, який:

• говорить з користувачем живою мовою,
• ставить запитання,
• парсить відповіді,
• викликає API,
• підтверджує успішні кроки,
• веде користувача до створення першої microDAO,
• налаштовує приватного агента,
• завершує онбординг фразою та редіректом.

---

2. Загальна архітектура

Усі дії будуються на:

• state-machine (опис нижче),
• Chat UI (аналог звичайного чату),
• репліках агента (скрипт),
• розпізнаванні наміру користувача (regex / LLM / кнопки),
• викликах API (з 03_api_core_snapshot.md).

Компоненти:

src/features/onboarding-agent/
  AgentOnboardingChat.tsx
  useOnboardingState.ts
  scripts/
    script.json
    parser.ts
    transitions.ts

---

3. State Machine

type OnboardingStep =
  | "greet"
  | "ask_profile"
  | "ask_team_name"
  | "ask_team_desc"
  | "ask_mode"
  | "ask_channel_name"
  | "ask_channel_type"
  | "ask_agent_enable"
  | "ask_agent_prefs"
  | "ask_invites"
  | "done";

Перехід між кроками базується на:

• відповіді користувача,
• успішності API-виклику.

---

4. Повний сценарій діалогу (репліки агента)

Нижче — готовий сценарій, який можна покласти в JSON або хардкод.

4.1. greet

Агент:

Привіт! Я — агент-провідник MicroDAO. Зараз ми разом створимо твою першу спільноту та особистого помічника. Як до тебе звертатися?

Після відповіді → ask_profile.

---

4.2. ask_profile

Агент:

Приємно познайомитися, {name}. Якою мовою хочеш працювати — українською чи англійською?

Після відповіді — зберегти locale → ask_team_name.

---

4.3. ask_team_name

Агент:

Як назвемо твою майбутню microDAO? Наприклад: "Креативна Майстерня", "AI-Команда Альфа", "Моя Спільнота".

Читаємо будь-який текст → POST /teams → ask_team_desc.

---

4.4. ask_team_desc

Агент:

Класно. А як би ти описав спільноту одним реченням? (Не обов'язково, можеш написати "пропустити".)

Зберегти опис → ask_mode.

---

4.5. ask_mode

Агент:

Обери режим для твоєї microDAO: 1) Відкрита — є публічний канал, гості можуть читати. 2) Приватна — тільки запрошені, чати зашифровані. Напиши 1 або 2.

Після відповіді:

• map → "public" / "confidential"
• PATCH /teams/{teamId} → ask_channel_name.

---

4.6. ask_channel_name

Агент:

Давай створимо перший канал. Як би ти хотів його назвати? (general, core, support)

Після відповіді → ask_channel_type.

---

4.7. ask_channel_type

Агент:

Це буде публічний канал чи приватна кімната? Напиши: public або private.

Mapping:

• public → type: "public"
• private → type: "group"

API: POST /channels

Після успіху → ask_agent_enable.

---

4.8. ask_agent_enable

Агент:

У MicroDAO кожна спільнота має власного ШІ-агента, який памʼятає контекст і самонавчається. Хочеш одразу створити командного агента?

Очікувані відповіді: так / ні.

• Якщо «ні» → ask_invites
• Якщо «так» → ask_agent_prefs

---

4.9. ask_agent_prefs

Агент:

Добре. Налаштуємо агента. Якою мовою він має відповідати?

Після відповіді →

Агент:

Який у нього фокус? Вибери одне: general, business, technical, creative.

Після відповіді →

Агент:

Що він має памʼятати?

1. Лише цей канал
2. Усі канали спільноти

Після відповіді:

Викликаємо: POST /agents

Потім → ask_invites.

---

4.10. ask_invites

Агент:

Все готово! Хочеш зараз запросити людей до своєї microDAO? Я підготую посилання, яке можна надіслати будь-кому.

Після відповіді — показати UI-елемент з інвайт-лінком.

→ done.

---

4.11. done

Агент:

Вітаю! Твоя microDAO {team.name} створена. Я створив канал #{channel.title} і готовий допомагати. Можеш почати працювати або поставити мені питання: "Що ти вмієш?" / "Як користуватися каналами?" / "Як запросити команду?"

redirect → /t/:teamId/c/:channelId.

---

5. Intent Parser (як агент розуміє відповіді)

Мінімальний підхід (regex):

function parseMode(input: string) {
  if (input.match(/1|пуб/i)) return "public";
  if (input.match(/2|прив/i)) return "confidential";
}

function parseYesNo(input: string) {
  if (input.match(/^так|yes|y$/i)) return true;
  if (input.match(/^ні|no|n$/i)) return false;
}

Або гібридний:

• парсимо regex,
• якщо незрозуміло → питаємо LLM: "Чи відповідь користувача означає Так/Ні/Інше?"

---

6. Компонент AgentOnboardingChat.tsx

Мінімальна структура:

export function AgentOnboardingChat() {
  const { step, setStep, state, updateState } = useOnboardingState();

  const handleUserMessage = async (text: string) => {
    addMessage({ author: "user", text });

    switch (step) {
      case "greet":
        updateState({ name: text });
        addAgent("Приємно познайомитися, " + text + "...");
        setStep("ask_profile");
        break;

      case "ask_profile":
        updateState({ locale: detectLocale(text) });
        addAgent("Як назвемо твою microDAO?");
        setStep("ask_team_name");
        break;

      case "ask_team_name":
        const team = await api.post("/teams", { name: text });
        updateState({ teamId: team.id });
        addAgent("А як би ти описав спільноту?");
        setStep("ask_team_desc");
        break;

      // ... і так далі для кожного step.
    }
  };

  return (
    <ChatUI
      messages={messages}
      onSend={handleUserMessage}
      agentAvatar="guide"
    />
  );
}

---

7. Acceptance Criteria (як перевіряти)

• /onboarding відкривається як чат.

• Користувач спілкується з агентом.

• На кожному кроці агент відповідає правильно.

• Усі API виклики працюють:

  • /teams
  • /teams/{id}
  • /channels
  • /agents

• Після завершення → redirect.

• UX: користувач не бачить жодної форми. Все — діалог.

---

8. Для Cursor

Коли ти даси йому задачу, використовуй цей формат:

You are a senior React/TS engineer.

Implement the Agent-first onboarding at `/onboarding` using the specification in:
- 08_agent_first_onboarding.md
- 03_api_core_snapshot.md
- 05_coding_standards.md

Create the component `AgentOnboardingChat.tsx` and supporting files.

Output:
- list of modified files
- diff
- summary

---

9. Інтеграція з існуючим кодом

9.1. Заміна класичного онбордингу

Існуючий OnboardingPage.tsx можна:

• залишити як fallback для користувачів, які не хочуть агентський онбординг,
• або повністю замінити на AgentOnboardingChat.

9.2. Використання API клієнтів

Використовувати існуючі API клієнти з src/api/:

• teams.ts — для створення команди
• channels.ts — для створення каналу
• agents.ts — для створення агента
• auth.ts — для автентифікації

9.3. State Management

Використовувати useOnboardingState hook або розширити існуючий useOnboarding.ts для агентського онбордингу.

---

10. UI/UX Вимоги

10.1. Chat Interface

• Повідомлення агента з аватаром
• Повідомлення користувача справа
• Індикатор набору тексту (typing indicator) під час обробки
• Кнопки швидких відповідей (опціонально)
• Плавні анімації появи повідомлень

10.2. Візуальні елементи

• Аватар агента (іконка або зображення)
• Індикатор прогресу онбордингу (опціонально)
• Підказки для користувача
• Обробка помилок з дружніми повідомленнями

10.3. Мобільна адаптація

• Адаптивний дизайн для мобільних пристроїв
• Зручний ввід тексту на мобільних
• Оптимізація для маленьких екранів

---

11. Обробка помилок

11.1. Помилки API

Якщо API виклик не вдався:

• Показати дружнє повідомлення від агента
• Запропонувати спробувати ще раз
• Зберегти стан, щоб не втратити прогрес

11.2. Незрозумілі відповіді

Якщо агент не розуміє відповідь:

• Задати уточнююче питання
• Показати приклади правильних відповідей
• Запропонувати кнопки з варіантами

11.3. Таймаути

• Обробка повільних API викликів
• Показ індикатора завантаження
• Повідомлення про затримку

---

12. Тестування

12.1. Unit Tests

• Тести для parser.ts (розпізнавання намірів)
• Тести для transitions.ts (переходи між станами)
• Тести для компонента AgentOnboardingChat

12.2. Integration Tests

• Тестування повного flow онбордингу
• Тестування API інтеграції
• Тестування обробки помилок

12.3. E2E Tests

• Повний сценарій онбордингу від початку до кінця
• Різні варіанти відповідей користувача
• Перевірка редіректу після завершення

---

13. Майбутні покращення

13.1. LLM Integration

• Використання LLM для розпізнавання намірів
• Більш природна мова агента
• Контекстне розуміння відповідей

13.2. Персоналізація

• Адаптація мови агента під користувача
• Запам'ятовування попередніх відповідей
• Рекомендації на основі профілю

13.3. Мультимовність

• Підтримка багатьох мов
• Автоматичне визначення мови
• Перемикання мови під час онбордингу

---

Готово.
Це повна специфікація агентського онбордингу, готова до використання в Cursor.