# 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).

Компоненти:

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

---

## 3. State Machine

```ts
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";
```text

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

- відповіді користувача,
- успішності 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):

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

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

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

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

---

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

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

```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"
    />
  );
}
```text

---

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

- `/onboarding` відкривається як чат.
- Користувач спілкується з агентом.
- На кожному кроці агент відповідає правильно.
- Усі API виклики працюють:

  - `/teams`
  - `/teams/{id}`
  - `/channels`
  - `/agents`
- Після завершення → redirect.
- UX: користувач не бачить жодної форми. Все — діалог.

---

## 8. Для Cursor

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

```text
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
```text

---

## 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.