Arc OS — Посібник користувача

Повний посібник по всіх можливостях Arc OS CRM Dashboard. Останнє оновлення: 2026-05-04 (Phase 52.1)

Карта можливостей одним поглядом

graph LR
    Login[1. Login + invite code]
    Dash[2. All Projects view]
    Onb[3. Create Project Wizard]
    Work[4. Workspace + Workers]
    Time[5. Timeline replay]
    Iss[6. Issues redesign]
    Skill[7. Skills + Sage]
    Wiki[8. Wiki + KG]
    NB[9. Neural Memory / RAG]
    Bill[10. Trial + Billing]

    Login --> Dash --> Onb --> Work
    Work --> Time
    Work --> Iss
    Work --> Skill
    Work --> Wiki --> NB
    Dash --> Bill

Зміст

1. Початок роботи
2. Структура Dashboard
3. Workspace — AI-працівники
4. Прикріплення файлів
5. Folders — файловий менеджер
6. Worker Studio — кастомні працівники
7. Issues
8. Wiki
9. Knowledge Graph
10. Skill Evolution
11. Roadmap
12. Reports
13. Analytics
14. Нейронна пам'ять — Self-hosted RAG
15. Cloud PM — чат проєкту
16. Налаштування проєкту
17. Інтеграція з Telegram
18. Тема та налаштування
19. Гарячі клавіші
20. Розв'язання проблем
21. Timeline (Phase 47)
22. Тріал-кредити та білінг
23. Бета-доступ — інвайт-коди

1. Початок роботи

Гейтинг бети (Phase 52.1): наразі публічна реєстрація доступна лише за запрошенням. Тобі потрібен інвайт-код у форматі arc-XXXX-XXXX, щоб створити обліковий запис. Дивись §23 Бета-доступ, як його отримати.

Onboarding Flow — сторіборд

sequenceDiagram
    autonumber
    actor U as You
    participant L as Login Screen
    participant E as Email
    participant W as Onboarding Wizard
    participant M as Master Bot
    participant Wo as Workspace

    U->>L: paste invite code arc-XXXX-XXXX
    L->>L: validate format
    U->>L: enter email + password + name
    L-->>E: send verification link (24h TTL)
    U->>E: click verification link
    E->>L: redirect → logged in
    L->>W: first-time user → wizard
    U->>W: name project · pick blueprint · set Anthropic key (optional)
    W->>M: POST /api/crm/onboarding/setup
    M->>M: allocatePort() · create dirs · clone blueprint · spawn child bot
    M-->>W: project ready
    W->>Wo: redirect to /project/<name>
    U->>Wo: send first message
    Wo-->>U: stream tokens via SSE

Бюджет часу: ціль ≤10 хв від вставки інвайт-коду до першої відповіді AI. Кроки 1-5 ≈ 3 хв, крок 6-9 ≈ 2 хв, перший чат ≈ 1-5 хв залежно від клонування blueprint.

Логін

Arc OS підтримує три методи автентифікації:

Варіант A: Email і пароль

1. Відкрий CRM dashboard (https://arc-os.co або http://<server>:18888).
2. Натисни Create Account на екрані логіну.
3. Введи email, відображуване ім'я, пароль і свій інвайт-код (arc-XXXX-XXXX).
4. Підтверди email через посилання, надіслане на твою скриньку (24h TTL).
5. Увійди з email і паролем.

Варіант B: OAuth (Google / GitHub)

1. Відкрий екран логіну CRM.
2. Натисни Continue with Google або Continue with GitHub.
3. Авторизуйся у спливному вікні.
4. Тебе автоматично переадресує назад і авторизує.

Усі методи створюють JWT-токен (дійсний 24 години), який зберігається у твоєму браузері.

Перші кроки

Після логіну ти побачиш вид All Projects. Використовуй випадаюче меню селектора Workspace у заголовку для перемикання між проєктами, або клікни All Projects, щоб побачити глобальний dashboard.

2. Структура Dashboard

Top Header

Sidebar

Згортуване навігаційне меню (натисни гамбургер для перемикання). Мобільна версія: оверлейний drawer з підкладкою.

Глобальні сторінки (видимі з All Projects):

• Analytics — огляд здоров'я системи, картки статусу проєктів
• Issues — крос-проєктний трекер задач
• Reports — аналітичні звіти
• Skills Registry — глобальне керування скілами через Sage Worker
• Files — файловий менеджер
• Нейронна пам'ять — семантичний пошук по контенту проєкту (Phase 71 self-hosted RAG)

Сторінки проєкту (видимі, коли вибрано проєкт):

• Workspace — AI-інтерфейс чату/термінала (основна робоча зона)
• Issues — трекер задач проєкту
• Roadmap — дорожня карта проєкту з фазами
• Reports — звіти проєкту
• Skills — еволюція скілів через Sage Worker, бенчмарки, маркетплейс
• Folders — файловий менеджер
• Wiki — сторінки бази знань
• Graph — візуалізація графа знань
• Project Settings — конфігурація проєкту, токен Telegram-бота, командні пресети

ContextRail (Right Panel, ≥1280px)

320-піксельна правобічна панель, що показує контекст проєкту поряд з активною сторінкою. Секції:

• Current Goal — підтягується з активної фази ROADMAP
• Metrics — сітка 2×2 (issues, skills, активність тощо)
• Active Skills — скіли, завантажені у поточну розмову Workspace
• Pinned notes — закріплені повідомлення працівників з тредів чату
• GitHub (Phase 49.3.1) — недавні події з підключених репозиторіїв. Автоматично приховується, якщо у проєкту немає підключених репо. Дивись GitHub Integration Setup.

3. Workspace — AI-працівники

Workspace — це твій основний інтерфейс взаємодії з AI. Він використовує систему Dynamic Worker, де кожен працівник є спеціалізованим AI-агентом.

Вбудовані працівники

Worker Bar

У верхній частині Workspace ти побачиш пілюлі працівників (кнопки):

• Активний (кольоровий) — панель видима
• Неактивний (сірий) — клікни, щоб показати панель
• Клікни пілюлю, щоб перемкнути панель працівника
• Принаймні один працівник має бути активним
• Layout зберігається для кожного проєкту (у localStorage)

Чат-працівники (Consultant)

Інтерфейс у стилі чат-бульбашок:

• Введи повідомлення у поле введення внизу
• Натисни Enter для відправки (або клікни кнопку Send)
• Натисни Shift+Enter для нового рядка
• Відповіді бота рендеряться у markdown (блоки коду, списки, заголовки)
• Клікни кнопку копіювання на будь-якому повідомленні асистента, щоб скопіювати його
• SSE streaming показує статус обробки в реальному часі

Термінал-працівники (Developer)

Лог-стрім інтерфейс термінала:

• Показує події виконання інструментів у реальному часі:
  • Thinking (іконка мозку, фіолетова пульсуюча анімація)
  • Виклики інструментів (Read, Edit, Bash, Grep тощо з деталями файлів/команд)
  • Текст відповіді (з кнопкою копіювання)
• Індикатор обробки: пульсуюча помаранчева крапка
• Індикатор простою: зелена крапка
• Зберігається до 300 записів логу

Селектор моделі

У нижній панелі інструментів кожної панелі працівника:

• Клікни випадаюче меню моделі, щоб перемкнути AI-модель
• Доступні моделі: Sonnet, Opus, Haiku
• Вибір моделі зберігається для кожного проєкту в localStorage

Quick Actions (нижня панель)

4. Прикріплення файлів

Ти можеш прикріплювати файли до будь-якого повідомлення працівника.

Як прикріпити

1. Клікни іконку скріпки в полі введення повідомлення, АБО
2. Перетягни-та-кинь файли у workspace, АБО
3. Встав зображення з буфера обміну

Підтримувані типи файлів

Чіпси прикріплень

Після прикріплення файли з'являються як чіпси над полем введення:

• Текстові файли показують ім'я файлу
• Зображення показують мініатюру 80x56px (клікни, щоб збільшити)
• PDF показують ім'я файлу з іконкою PDF
• Клікни X на будь-якому чіпсі, щоб видалити його

Ліміти розміру

• Текстові файли: до 512KB
• Зображення: автостиснення (без жорсткого ліміту, на виході ~100-500KB)
• PDF: передаються як base64 (рекомендовано < 10MB)

5. Folders — файловий менеджер

Сторінка Folders надає повний файловий браузер для каталогу твого проєкту на сервері.

Навігація

• Шлях у вигляді хлібних крихт угорі — клікни будь-який сегмент, щоб перейти до цієї директорії
• Клікни папку, щоб відкрити її
• Клікни файл, щоб переглянути його у бічній панелі

Дії панелі інструментів

Контекстне меню (правий клік)

Правий клік на будь-якому елементі для додаткових опцій:

На файлах:

• Open — перегляд у бічній панелі
• Preview — те саме що Open
• Download — завантажити файл на твій комп'ютер
• Delete — видалити файл (з підтвердженням)

На папках:

• Open — перейти в папку
• Delete — рекурсивно видалити папку (з підтвердженням)

На порожньому місці:

• Upload, New Folder, New File, Add Link, Clone Repo

Панель попереднього перегляду файлу

Коли ти клікаєш на файл, відкривається бічна панель, що показує:

• Шлях до файлу та метадані (розмір, дата зміни)
• Вміст з підсвічуванням синтаксису для текстових файлів
• Кнопка закриття (X) або клік за межами для закриття

6. Worker Studio — кастомні працівники

Ти можеш створювати кастомних AI-працівників, адаптованих під потреби твого проєкту.

Створення працівника

1. У Workspace клікни іконку шестерні (Worker Studio) у панелі працівників
2. Клікни + New Worker
3. Заповни конфігурацію працівника:

AI-генеровані системні промпти

Клікни Generate with AI, щоб автоматично створити системний промпт на основі:

• Label та типу працівника
• Вибраних інструментів
• Focus-директорій
• Структури твого проєкту

Telegram Bot Token

Кожен працівник може мати власного виділеного Telegram-бота:

1. Редагуй працівника у Worker Studio
2. У секції Telegram Bot Token встав токен бота (від @BotFather)
3. Клікни Connect
4. Бот працівника запускається автоматично і обробляє повідомлення незалежно
5. Щоб видалити: клікни Disconnect

Це дозволяє мати окремі Telegram-боти для кожного працівника — напр., бот Consultant з доступом тільки для читання та бот Developer з повним доступом.

Керування працівниками

• Edit: клікни іконку редагування на будь-якому кастомному працівнику у Worker Studio
• Delete: клікни іконку видалення (вбудованих працівників видалити не можна)
• Працівники зберігаються у реєстрі працівників сервера

7. Issues

Сторінка Issues — це повноцінний трекер задач для твого проєкту.

Можливості

• Створення issues з заголовком, описом, пріоритетом (P0-P3) та лейблами
• Workflow статусу: Open → In Progress → Done / Closed
• Activity log: додавай нотатки прогресу до будь-якого issue через форму запису логу
• Фільтр за статусом (open, closed, all)
• Пошук issues за текстом

З CLI

Issues також можна керувати через ARC CLI:

arc issues                         # list open issues
arc issue create --title "Bug..." # create new issue
arc issue log <id> "Fixed X"      # add activity log entry

8. Wiki

Сторінка Wiki — це база знань для твого проєкту.

Можливості

• Створення сторінок з заголовком та markdown-вмістом
• Редагування існуючих сторінок через вбудований markdown-редактор
• Авто-embed у RAG-індекс при збереженні (Phase 71.5 hook); семантичний пошук через arc kb search або chat ask_notebooklm tool підхоплює зміни автоматично
• Сторінки зберігаються окремо для кожного проєкту на сервері

9. Knowledge Graph

Сторінка Graph візуалізує зв'язки між сутностями проєкту (issues, wiki-сторінки, скіли, фази roadmap) як інтерактивний граф вузлів.

• Вузли представляють різні типи сутностей (з кольоровим кодуванням)
• Ребра показують зв'язки між сутностями
• Клікни вузол, щоб побачити деталі
• Перетягуй для панорамування, прокручуй для масштабування

10. Skill Evolution

Сторінка Skill Evolution (називається «Skills» у sidebar проєкту, «Skills Registry» у глобальному sidebar) надає просунуте керування скілами.

Двопанельний layout

• Ліва панель: skill-explorer — список усіх скілів з пошуком/фільтром
• Права панель: деталі скілу з 4 вкладками:
  • Overview — опис скілу, метадані, історія версій
  • Evals — правила валідації якості
  • Evolution — лог змін та історія версій
  • Benchmarks — результати A/B-тестів

Sage Worker

Sage — це AI-аналізатор скілів:

• Analyze: вибери скіл → клікни «Sage Analyze» → отримай рекомендації для покращення
• Benchmark: запусти A/B-тести, що порівнюють версії скілу
• Marketplace Discovery: пошук на claudemarketplaces.com по скілах спільноти → аналіз сумісності → встановлення глобально або для конкретного проєкту

Skill Forks

Форкни глобальний скіл, щоб кастомізувати його для конкретного проєкту. Форк відстежує батьківський скіл і може підтягувати оновлення.

11. Roadmap

Сторінка Roadmap показує план розробки проєкту, організований за фазами.

• Перегляд завершених, у процесі та запланованих фаз
• Кожна фаза має опис і статус
• Синхронізується через CLI-команду arc roadmap sync

12. Reports

Сторінка Reports показує аналітичні та сесійні звіти.

• Перегляд минулих сесійних звітів, надісланих через arc report
• Відстеження виконаної роботи за сесію

13. Analytics

Сторінка Analytics (глобальний вид) показує здоров'я та метрики системи в цілому:

• Картки статусу проєктів з індикаторами здоров'я
• Огляд системи з даними про uptime та продуктивність

14. Нейронна пам'ять — Self-hosted RAG (Phase 71)

Семантичний пошук по wiki + issues + skills проєкту працює через self-hosted RAG з 2026-06-05. Жодного зовнішнього retrieval-сервісу, жодної Google-сесії.

• Авто-embed. Wiki / issue / skill records проходять через Phase 71.5 hooks автоматично — нічого клікати не треба. Наступний arc kb search або chat ask_notebooklm бачить свіжий контент.
• Cross-lingual. UK query знаходить EN контент (і навпаки). Перевірено 100% recall на grounded test pairs.
• Sidebar. Стара вкладка "Neural Memory" з посиланням на Google NotebookLM прибрана разом із сервісом; семантичні результати тепер показуються у Wiki / KnowledgeGraph + у тілі chat-відповіді.
• CLI. arc kb search "<query>" — той самий retrieval що використовує chat.

Спец: RAG Architecture. NotebookLM bridge виведено з експлуатації 2026-06-05; legacy guide у notebooklm-bridge.md.

15. Cloud PM — чат проєкту

Cloud PM — це постійний чат проєкту, доступний з Workspace:

• Інтерфейс чату на основі Claude (Anthropic API)
• Повідомлення зберігаються у БД з курсорною пагінацією
• Окремо від розмов працівників — використовується для обговорень керування проєктом
• Історія зберігається між сесіями

16. Налаштування проєкту

Сторінка Project Settings (доступна через кнопку Settings у sidebar) надає:

• Інформація проєкту: відображуване ім'я, опис
• Telegram Bot Token: підключи Telegram-бот рівня проєкту (від @BotFather)
• Командні пресети: налаштуй склад команди та дефолти працівників
• Danger zone: видалення проєкту

17. Інтеграція з Telegram

Telegram-бот — це альтернативний командний інтерфейс. Усі функції CRM dashboard також доступні через Telegram.

Команди Master Bot

Команди Child Bot

Маршрутизація повідомлень

Telegram-боти для конкретних працівників

Кожен працівник може мати власний Telegram-токен бота (налаштовується у Worker Studio). Коли працівник має власного бота:

• Повідомлення, надіслані до цього бота, йдуть напряму до цього працівника
• Префікс /c чи /d не потрібен
• Відповіді з'являються і в Telegram, і в CRM

Інлайн-кнопки

Після кожної відповіді бота з'являються інлайн-кнопки:

• Stop — завершити поточний підпроцес
• Pause / Resume — заморозити/розморозити підпроцес
• BTW — поставити в чергу додатковий контекст для наступного повідомлення
• Fix It — повторно запустити з промптом «fix the previous response»
• Thumbs up/down — фідбек по якості (тренує систему навчання)

18. Тема та налаштування

Темний/світлий режим

Клікни перемикач теми у верхньому header, щоб переключитися між світлою та темною темами. Твоя перевага зберігається в localStorage.

Налаштування облікового запису

Клікни на свій аватар → Account Settings, щоб налаштувати:

• Відображуване ім'я
• Перевагу мови (English / Ukrainian)
• Налаштування сповіщень

Колірна система

Dashboard використовує CSS custom properties для консистентної темізації:

• Світлий режим: чисті білі фони, ненав'язливі бордери
• Темний режим: темні slate-фони, пом'якшений текст

Кольори статусу

19. Гарячі клавіші

20. Розв'язання проблем

«Connection lost» / Червоний індикатор

Dashboard втратив з'єднання з сервером. Перевір:

1. Чи працює VPS? (ssh на сервер, перевір tmux ls)
2. Чи працює nginx? (systemctl status nginx)
3. Чи працює master-бот? (curl http://<server>:19210/api/master/health)

«Unauthorized» / цикл логіну

Твій JWT-токен прострочений (24h TTL). Увійди знову через email/пароль або OAuth.

Панель працівника не показує виводу

1. Перевір, чи підключений SSE-стрім (DevTools браузера → Network → фільтр за EventStream)
2. Працівник може ще не згенерувати вивід — спочатку надішли повідомлення
3. Спробуй оновити сторінку (F5)

Завантаження файлу не вдається

• Перевір розмір файлу (text < 512KB, images авто-стискається, PDFs < 10MB рекомендовано)
• Переконайся, що тип файлу підтримується (дивись Прикріплення файлів)
• Перевір консоль браузера на помилки

Бот не відповідає в Telegram

1. Перевір здоров'я бота: надішли /ping
2. Якщо відповіді немає, SSH на VPS і перевір tmux: tmux attach -t citadel-child
3. Перевір логи: tail -50 /var/log/citadel/<project>/system-$(date +%Y-%m-%d).log
4. Перезапусти через CRM: Project Settings → Restart Bot, або /deploy у Master Bot

CORS-помилки в консолі браузера

Домен dashboard має бути в CRM_ALLOWED_ORIGINS. За замовчуванням дозволено:

• https://arc-os.co
• http://localhost:5173 (dev)
• http://62.171.128.248:18888 (production)

invite_required 403 при реєстрації (Phase 52.1)

Публічна реєстрація закрита. Або:

• Отримай інвайт-код від Founding Member чи каналу @arcos_beta_feedback
• Твій код відкликали? Запитай CEO напряму (DM); відкликання логуються у таблиці invites

plan_limit_reached 402 при створенні проєкту / працівника (Phase 51)

Твій акаунт досяг ліміту твого тарифу:

• Free — 1 проєкт / 5 працівників
• Min ($4.99/mo) — 5 OR 25 (OR-семантика)
• Max ($11.99/mo) — 20 OR 150
• Beta — без лічильника (призначається вручну для F&F-тестерів)

Апгрейд через Settings → Billing (UI Stage 3 у роботі). Поки що звертайся до CEO.

21. Timeline (Phase 47)

Сторінка спостережності у стилі DAW, що дозволяє відтворити сесію працівника так, ніби це аудіо-мікшер.

sequenceDiagram
    participant U as You
    participant W as Workspace
    participant T as Timeline
    participant DB as timeline_events table

    U->>W: send message to Worker A
    W->>DB: append events (think · tool · response)
    U->>T: open Timeline page
    T->>DB: query events grouped by worker
    T-->>U: render lanes + playhead
    U->>T: scrub playhead / mute/solo lanes

Можливості

• Доріжки працівників — один рядок на активного працівника, як мультитрек-аудіо
• Чіпси подій — з кольоровим кодуванням: thinking (фіолетовий), tool calls (синій), responses (зелений), errors (червоний)
• Mute / Solo (M/S) — приховай одного працівника або ізолюй його; зберігається в localStorage
• Скрабінг playhead — перетягни до моменту в часі; події підсвічуються при проходженні
• Продуктивність — підтримується SQLite-таблицею timeline_events (міграція 014); мілісекундні таймстемпи

Коли використовувати

• Дебаг застряглого працівника — побачити, який саме виклик інструменту завис
• Аудит довгої сесії — швидко знайти, коли було прийняте критичне рішення
• Демо системи — візуальний доказ того, що працівники реально виконують роботу

22. Тріал-кредити та білінг (Phases 50-51)

Arc OS використовує API Anthropic від твого імені для чат/термінал-працівників. Базова платформа безкоштовна, але токенові витрати перекладаються на твій акаунт.

Тріал-кредити (Phase 50)

• Безкоштовний тріал — кожен новий email отримує одноразовий запас кредитів (відхиляється, якщо email уже використовувався)
• Без картки — не потрібна кредитна картка для старту; кредити зменшуються по мірі роботи працівників
• Таблиця trial_credits — ключ за email, ніколи не поповнюється апгрейдом

Stripe Billing (Phase 51 — Stage 1 в роботі, UI Stage 3 очікується)

OR-семантика лімітів: «5 OR 25» означає, що ти можеш мати або ≤5 проєктів, АБО ≤25 працівників усього — який ліміт досягнеш першим.

Власний ключ

Якщо хочеш платити Anthropic напряму:

1. Отримай Anthropic API-ключ на https://console.anthropic.com
2. Account Settings → API Keys → встав ключ
3. Або використай Local Bridge CLI, щоб запускати працівників на власній машині безкоштовно

Endpoint статусу

GET /api/crm/billing/status повертає:

• Поточний план + ціну
• Снепшот використання (проєкти, працівники, витрати на anthropic)
• Ліміти плану + залишок
• Feature-флаги (які преміум-функції увімкнені)

23. Бета-доступ — інвайт-коди (Phase 52.1)

Arc OS перебуває у Friends & Family beta. Публічна реєстрація закрита, поки не будуть валідовані критерії успіху F&F.

Як отримати інвайт

• Від Founding Member — будь-хто з активним інвайт-кодом може мінтити саб-інвайти
• Через Telegram-канал @arcos_beta_feedback — періодичні батчі від CEO
• Прямий запит — DM CEO, якщо у тебе є сильний use case

Формат коду

arc-XXXX-XXXX — префікс arc- + 8 hex-символів у двох групах через дефіс (отримано через crypto.randomBytes).

Використання коду

1. Перейди до форми реєстрації
2. Встав код у поле Invite Code (моноширинне поле введення, валідується на клієнті)
3. Код споживається атомарно при успішній реєстрації — один код на акаунт
4. Якщо код уже використано чи відкликано: 403 invite_required з посиланням назад на канал фідбеку

Переваги Founding Member

• Довічна знижка 50%, коли відбудеться публічний запуск
• Бейдж Founding Member у профілі (публічний профіль)
• Прямий Slack/Discord-доступ до команди Arc OS після запуску
• Ім'я на публічній Founders Wall на https://arc-os.co/founders (за згодою)

Адмін: мінтинг та відкликання кодів (тільки CEO)

arc invites generate --count 5            # mint 5 fresh codes
arc invites list                          # show active codes + who used them
arc invites revoke arc-AAAA-BBBB          # invalidate a leaked code

REST-еквіваленти: POST/GET/DELETE /api/crm/admin/invites (потрібна роль admin).

Підтримується командою Arc OS. Оновлюється після завершення кожної фази.