Arc OS — User Guide

Complete guide to all features of the Arc OS CRM Dashboard. Last updated: 2026-05-04 (Phase 52.1)

At-a-glance feature map

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

Table of Contents

1. Getting Started
2. Dashboard Layout
3. Workspace — AI Workers
4. File Attachments
5. Folders — File Manager
6. Worker Studio — Custom Workers
7. Issues
8. Wiki
9. Knowledge Graph
10. Skill Evolution
11. Roadmap
12. Reports
13. Analytics
14. Neural Memory — Self-hosted RAG
15. Cloud PM — Project Chat
16. Project Settings
17. Telegram Integration
18. Theme & Settings
19. Keyboard Shortcuts
20. Troubleshooting
21. Timeline (Phase 47)
22. Trial Credits & Billing
23. Beta Access — Invite Codes

1. Getting Started

Beta gating (Phase 52.1): Public registration is currently invite-only. You need an invite code in the format arc-XXXX-XXXX to create an account. See §23 Beta Access for how to get one.

Onboarding Flow — Storyboard

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

Time budget: target ≤10 min from invite-code paste to first AI response. Steps 1-5 ≈ 3 min, step 6-9 ≈ 2 min, first chat ≈ 1-5 min depending on blueprint clone.

Login

Arc OS supports three authentication methods:

Option A: Email & Password

1. Open the CRM dashboard (https://arc-os.co or http://<server>:18888).
2. Click Create Account on the login screen.
3. Enter your email, display name, password, and your invite code (arc-XXXX-XXXX).
4. Verify your email via the link sent to your inbox (24h TTL).
5. Log in with email and password.

Option B: OAuth (Google / GitHub)

1. Open the CRM login screen.
2. Click Continue with Google or Continue with GitHub.
3. Authorize in the popup window.
4. You'll be redirected back and logged in automatically.

All methods produce a JWT token (valid 24 hours) stored in your browser.

First Steps

After login, you'll see the All Projects view. Use the workspace selector dropdown in the header to switch between projects, or click All Projects to see the global dashboard.

2. Dashboard Layout

Top Header

Sidebar

Collapsible navigation menu (click hamburger to toggle). Mobile: overlay drawer with backdrop.

Global pages (visible from All Projects):

• Analytics — system health overview, project status cards
• Issues — cross-project issue tracker
• Reports — analytics reports
• Skills Registry — global skill management with Sage Worker
• Files — file manager
• Neural Memory — semantic search across project content (Phase 71 self-hosted RAG)

Project pages (visible when a project is selected):

• Workspace — AI chat/terminal interface (main working area)
• Issues — project issue tracker
• Roadmap — project roadmap with phases
• Reports — project reports
• Skills — skill evolution with Sage Worker, benchmarks, marketplace
• Folders — file manager
• Wiki — knowledge base pages
• Graph — knowledge graph visualization
• Project Settings — project configuration, Telegram bot token, team presets

ContextRail (Right Panel, ≥1280px)

A 320px right-side panel showing project context alongside the active page. Sections:

• Current Goal — pulled from ROADMAP active phase
• Metrics — 2×2 grid (issues, skills, activity, etc.)
• Active Skills — skills loaded into current Workspace conversation
• Pinned notes — pinned worker messages from chat threads
• GitHub (Phase 49.3.1) — recent events from linked repos. Auto-hidden if project has no linked repos. See GitHub Integration Setup.

3. Workspace — AI Workers

The Workspace is your main interface for interacting with AI. It uses a Dynamic Worker system where each worker is a specialized AI agent.

Built-in Workers

Worker Bar

At the top of the Workspace, you'll see worker pills (buttons):

• Active (colored) — panel is visible
• Inactive (grayed) — click to show panel
• Click a pill to toggle the worker panel on/off
• At least one worker must be active
• Layout persists per project (saved in localStorage)

Chat Workers (Consultant)

Chat-style bubble interface:

• Type your message in the input field at the bottom
• Press Enter to send (or click Send button)
• Press Shift+Enter for a new line
• Bot responses render in markdown (code blocks, lists, headers)
• Click the copy button on any assistant message to copy it
• SSE streaming shows real-time processing status

Terminal Workers (Developer)

Log-stream terminal interface:

• Shows real-time tool execution events:
  • Thinking (brain icon, purple pulsing animation)
  • Tool calls (Read, Edit, Bash, Grep, etc. with file/command details)
  • Response text (with copy button)
• Processing indicator: pulsing orange dot
• Idle indicator: green dot
• Up to 300 log entries retained

Model Selector

In the bottom toolbar of each worker panel:

• Click the model dropdown to switch AI model
• Available models: Sonnet, Opus, Haiku
• Model choice persists per project in localStorage

Quick Actions (Bottom Bar)

4. File Attachments

You can attach files to any worker message.

How to Attach

1. Click the paperclip icon in the message input area, OR
2. Drag-and-drop files onto the workspace, OR
3. Paste an image from clipboard

Supported File Types

Attachment Chips

After attaching, files appear as chips above the input:

• Text files show filename
• Images show a 80x56px thumbnail (click to enlarge)
• PDFs show filename with PDF icon
• Click X on any chip to remove it

Size Limits

• Text files: up to 512KB
• Images: auto-compressed (no hard limit, compressed output ~100-500KB)
• PDFs: transmitted as base64 (recommended < 10MB)

5. Folders — File Manager

The Folders page provides a full file browser for your project directory on the server.

Navigation

• Breadcrumb path at the top — click any segment to jump to that directory
• Click a folder to open it
• Click a file to preview it in the side panel

Toolbar Actions

Context Menu (Right-click)

Right-click on any item for additional options:

On files:

• Open — preview in side panel
• Preview — same as Open
• Download — download file to your computer
• Delete — delete file (with confirmation)

On folders:

• Open — navigate into folder
• Delete — delete folder recursively (with confirmation)

On empty space:

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

File Preview Panel

When you click a file, a side panel opens showing:

• File path and metadata (size, modified date)
• Syntax-highlighted content for text files
• Close button (X) or click outside to dismiss

6. Worker Studio — Custom Workers

You can create custom AI workers tailored to your project needs.

Creating a Worker

1. In the Workspace, click the gear icon (Worker Studio) in the worker bar
2. Click + New Worker
3. Fill in the worker configuration:

AI-Generated System Prompts

Click Generate with AI to auto-create a system prompt based on:

• Worker label and type
• Selected tools
• Focus directories
• Your project structure

Telegram Bot Token

Each worker can have its own dedicated Telegram bot:

1. Edit a worker in Worker Studio
2. In the Telegram Bot Token section, paste a bot token (from @BotFather)
3. Click Connect
4. The worker bot starts automatically and handles messages independently
5. To remove: click Disconnect

This allows per-worker Telegram bots — e.g., a Consultant bot with read-only access and a Developer bot with full access.

Managing Workers

• Edit: Click the edit icon on any custom worker in Worker Studio
• Delete: Click the delete icon (builtin workers cannot be deleted)
• Workers are stored in the server's worker registry

7. Issues

The Issues page is a full issue tracker for your project.

Features

• Create issues with title, description, priority (P0-P3), and labels
• Status workflow: Open → In Progress → Done / Closed
• Activity log: Add progress notes to any issue via the log entry form
• Filter by status (open, closed, all)
• Search issues by text

From CLI

Issues can also be managed via the 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

The Wiki page is a knowledge base for your project.

Features

• Create pages with a title and markdown content
• Edit existing pages with the built-in markdown editor
• Auto-embed to the project RAG index on save (Phase 71.5 hook); semantic search via arc kb search or the in-chat ask_notebooklm tool picks it up automatically
• Pages are stored per-project on the server

9. Knowledge Graph

The Graph page visualizes relationships between project entities (issues, wiki pages, skills, roadmap phases) as an interactive node graph.

• Nodes represent different entity types (color-coded)
• Edges show relationships between entities
• Click a node to see details
• Drag to pan, scroll to zoom

10. Skill Evolution

The Skill Evolution page (called "Skills" in project sidebar, "Skills Registry" in global sidebar) provides advanced skill management.

Two-Panel Layout

• Left panel: Skill explorer — list of all skills with search/filter
• Right panel: Skill detail with 4 tabs:
  • Overview — skill description, metadata, version history
  • Evals — quality validation rules
  • Evolution — change log and version history
  • Benchmarks — A/B test results

Sage Worker

The Sage is an AI-powered skill analyzer:

• Analyze: Select a skill → click "Sage Analyze" → get improvement recommendations
• Benchmark: Run A/B tests comparing skill versions
• Marketplace Discovery: Search claudemarketplaces.com for community skills → analyze compatibility → install globally or per-project

Skill Forks

Fork a global skill to customize it for a specific project. The fork tracks the parent skill and can pull updates.

11. Roadmap

The Roadmap page shows the project's development plan organized by phases.

• View completed, in-progress, and planned phases
• Each phase has a description and status
• Synced via arc roadmap sync CLI command

12. Reports

The Reports page shows analytics and session reports.

• View past session reports submitted via arc report
• Track work done per session

13. Analytics

The Analytics page (global view) shows system-wide health and metrics:

• Project status cards with health indicators
• System overview with uptime and performance data

14. Neural Memory — Self-hosted RAG (Phase 71)

Semantic search across the project's wiki + issues + skills runs through the self-hosted RAG pipeline since 2026-06-05. No external retrieval service, no Google session.

• Auto-embed. Wiki / issue / skill writes go through Phase 71.5 hooks automatically — nothing to click. The next arc kb search or chat ask_notebooklm call sees the new content.
• Cross-lingual. A UK query can surface EN content (and vice versa). Tested 100% recall on a hand-grounded pair set.
• Sidebar. The old "Neural Memory" sidebar item pointing to Google NotebookLM was retired together with the bridge service; semantic results now show inside the existing Wiki / KnowledgeGraph surfaces and the chat answer body.
• CLI. arc kb search "<query>" runs the same retrieval the chat uses; results are project-scoped with optional _global_ skill merge.

Spec: RAG Architecture. The Phase 36 NotebookLM bridge was decommissioned 2026-06-05; legacy guide at notebooklm-bridge.md.

15. Cloud PM — Project Chat

The Cloud PM is a persistent project chat accessible from the Workspace:

• Chat interface powered by Claude (Anthropic API)
• Messages saved to database with cursor-based pagination
• Separate from worker conversations — used for project management discussions
• History persists across sessions

16. Project Settings

The Project Settings page (accessible via Settings button in sidebar) provides:

• Project info: display name, description
• Telegram Bot Token: Connect a project-level Telegram bot (from @BotFather)
• Team presets: Configure team composition and worker defaults
• Danger zone: project removal

17. Telegram Integration

The Telegram bot is an alternative command interface. All CRM dashboard features are also accessible via Telegram.

Master Bot Commands

Child Bot Commands

Message Routing

Worker-Specific Telegram Bots

Each worker can have its own Telegram bot token (configured in Worker Studio). When a worker has its own bot:

• Messages sent to that bot go directly to that worker
• No /c or /d prefix needed
• Responses appear in both Telegram and CRM

Inline Buttons

After each bot response, inline buttons appear:

• Stop — kill current subprocess
• Pause / Resume — freeze/unfreeze subprocess
• BTW — queue additional context for next message
• Fix It — re-run with "fix the previous response" prompt
• Thumbs up/down — quality feedback (trains the learning system)

18. Theme & Settings

Dark/Light Mode

Click the theme toggle in the top header to switch between light and dark themes. Your preference is saved in localStorage.

Account Settings

Click your avatar → Account Settings to configure:

• Display name
• Language preference (English / Ukrainian)
• Notification settings

Color System

The dashboard uses CSS custom properties for consistent theming:

• Light mode: clean white backgrounds, subtle borders
• Dark mode: dark slate backgrounds, softened text

Status Colors

19. Keyboard Shortcuts

20. Troubleshooting

"Connection lost" / Red indicator

The dashboard lost connection to the server. Check:

1. Is the VPS running? (ssh into server, check tmux ls)
2. Is nginx running? (systemctl status nginx)
3. Is the master bot running? (curl http://<server>:19210/api/master/health)

"Unauthorized" / Login loop

Your JWT token has expired (24h TTL). Log in again via email/password or OAuth.

Worker panel shows no output

1. Check that SSE stream is connected (browser DevTools → Network → filter by EventStream)
2. The worker may not have produced output yet — send a message first
3. Try refreshing the page (F5)

File upload fails

• Check file size (text < 512KB, images auto-compressed, PDFs < 10MB recommended)
• Ensure the file type is supported (see File Attachments)
• Check browser console for errors

Bot not responding in Telegram

1. Check bot health: send /ping
2. If no response, SSH to VPS and check tmux: tmux attach -t citadel-child
3. Check logs: tail -50 /var/log/citadel/<project>/system-$(date +%Y-%m-%d).log
4. Restart via CRM: Project Settings → Restart Bot, or /deploy in Master Bot

CORS errors in browser console

The dashboard domain must be in CRM_ALLOWED_ORIGINS. Default allowed:

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

invite_required 403 on signup (Phase 52.1)

Public signup is gated. Either:

• Get an invite code from a Founding Member or @arcos_beta_feedback channel
• Have your code revoked? Ask the CEO directly (DM); revocation is logged in invites table

plan_limit_reached 402 on project / worker create (Phase 51)

Your account hit the limit of your tier:

• Free — 1 project / 5 workers
• Min ($4.99/mo) — 5 OR 25 (OR-semantic)
• Max ($11.99/mo) — 20 OR 150
• Beta — unmetered (assigned manually to F&F testers)

Upgrade via Settings → Billing (Stage 3 UI is in flight). For now contact CEO.

21. Timeline (Phase 47)

A DAW-style observability page that lets you replay a worker's session as if it were an audio mixing console.

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

Features

• Worker lanes — one row per active worker, like multitrack audio
• Event chips — color-coded: thinking (purple), tool calls (blue), responses (green), errors (red)
• Mute / Solo (M/S) — hide one worker or isolate it; localStorage-persistent
• Playhead scrubbing — drag to a moment in time; events highlight as you pass them
• Performance — backed by SQLite timeline_events table (migration 014); millisecond timestamps

When to use

• Debugging a stuck worker — see exactly which tool call hung
• Auditing a long session — quickly find when a critical decision was made
• Demoing the system — visual proof that workers actually do the work

22. Trial Credits & Billing (Phases 50-51)

Arc OS uses Anthropic's API on your behalf for chat/terminal workers. The base platform is free, but token costs are passed through to your account.

Trial Credits (Phase 50)

• Free trial — every new email gets a one-time credit allowance (rejected if email already used)
• No-card — no credit card required to start; credits decrement as workers run
• trial_credits table — keyed by email, never refilled by upgrade

Billing — Plata by Mono (Phase 65)

OR-semantic limits: "5 OR 25" means you can have either ≤5 projects OR ≤25 workers across all projects — whichever you hit first. Payments processed via Plata by Mono (Ukrainian acquiring).

Bringing your own key

If you'd rather pay Anthropic directly:

1. Get an Anthropic API key from https://console.anthropic.com
2. Account Settings → API Keys → paste key
3. Or use the Local Bridge CLI to run workers on your own machine for free

Status endpoint

GET /api/crm/billing/status returns:

• Current plan + price
• Usage snapshot (projects, workers, anthropic spend)
• Plan limits + remaining
• Feature flags (which premium features are enabled)

23. Beta Access — Invite Codes (Phase 52.1)

Arc OS is in Friends & Family beta. Public signup is closed until F&F success criteria are validated.

Getting an invite

• From a Founding Member — anyone with an active invite code can mint sub-invites
• From the @arcos_beta_feedback Telegram channel — periodic batches dropped by the CEO
• Direct ask — DM the CEO if you have a strong use case

Code format

arc-XXXX-XXXX — arc- prefix + 8 hex chars in two hyphenated groups (crypto.randomBytes derived).

Using a code

1. Go to the signup form
2. Paste the code into the Invite Code field (monospace input, validated client-side)
3. The code is consumed atomically on successful signup — one code per account
4. If the code is already used or revoked: 403 invite_required with a link back to feedback channel

Founding Member benefits

• Lifetime 50% discount when public launch happens
• Founding Member profile badge (public profile)
• Direct Slack/Discord access to Arc OS team post-launch
• Name on the public Founders Wall at https://arc-os.co/founders (opt-in)

Admin: minting & revoking codes (CEO only)

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 equivalents: POST/GET/DELETE /api/crm/admin/invites (admin role required).

Maintained by Arc OS Team. Updated after each phase completion.