163 lines
4.8 KiB
Markdown
163 lines
4.8 KiB
Markdown
# Getting Started
|
||
|
||
[← Docs index](./README.md)
|
||
|
||
This guide gets Fusion running, explains first-run setup, and walks through your first task from creation to completion.
|
||
|
||
## Prerequisites
|
||
|
||
Fusion uses the `pi` agent runtime for AI sessions.
|
||
|
||
1. Install pi:
|
||
|
||
```bash
|
||
npm i -g @mariozechner/pi-coding-agent
|
||
```
|
||
|
||
2. Authenticate pi (for example with `/login`) or configure provider API keys.
|
||
|
||
```bash
|
||
pi
|
||
```
|
||
|
||
## Install Fusion
|
||
|
||
Install the published CLI package globally:
|
||
|
||
```bash
|
||
npm i -g @gsxdsm/fusion
|
||
```
|
||
|
||
Then verify install:
|
||
|
||
```bash
|
||
fn --help
|
||
```
|
||
|
||
## First Run and Onboarding
|
||
|
||
Start the dashboard:
|
||
|
||
```bash
|
||
fn dashboard
|
||
```
|
||
|
||
On first launch, Fusion automatically opens the **onboarding wizard**. It guides you through three steps:
|
||
|
||
1. **AI Setup** — Connect an AI provider and choose a default model. Authenticate via OAuth login (for supported providers like OpenAI Codex) or enter an API key directly.
|
||
|
||
2. **GitHub (Optional)** — Connect GitHub to import issues and manage pull requests. This step is optional — you can continue without GitHub.
|
||
|
||
3. **First Task** — Get started by creating your first task or importing from GitHub.
|
||
|
||
**The onboarding wizard is dismissible and non-blocking.** If you skip setup, you can complete it later — and you can always update your AI provider authentication anytime via **Settings → Authentication** in the dashboard:
|
||
- Click **Skip for now** to dismiss the wizard — the dashboard remains fully usable
|
||
- After dismissing, a **Continue Setup** banner appears at the top of the dashboard, letting you resume from where you left off
|
||
- Re-open onboarding anytime from **Settings → Authentication → Reopen onboarding guide**
|
||
|
||
When reopening onboarding, the wizard pre-populates your previously saved AI provider and default model, so you can quickly review or update your setup.
|
||
|
||
Onboarding completion is tracked by `modelOnboardingComplete` in global settings.
|
||
|
||
## Start the Dashboard
|
||
|
||
Common startup options:
|
||
|
||
```bash
|
||
fn dashboard # default port 4040
|
||
fn dashboard --port 5050 # custom port
|
||
fn dashboard -p 5050 # short form for --port
|
||
fn dashboard --interactive # choose port interactively
|
||
fn dashboard --paused # start with automation paused
|
||
fn dashboard --dev # run UI only (no engine)
|
||
```
|
||
|
||
Open: `http://localhost:4040` (or your custom port).
|
||
|
||
Other launch modes:
|
||
|
||
```bash
|
||
fn serve --port 5050 --host 0.0.0.0 # headless node (API + engine, no web UI)
|
||
fn daemon --port 5050 # daemon mode with token auth support
|
||
fn desktop # launch Electron desktop app
|
||
```
|
||
|
||
## Create Your First Task
|
||
|
||
You can create tasks from the board or CLI.
|
||
|
||
### Option A: Quick Entry (Board)
|
||
|
||
1. Type a short request in the quick entry input.
|
||
2. Press Enter.
|
||
3. Task appears in **Triage** and the triage agent generates `PROMPT.md`.
|
||
|
||
### Option B: Plan Mode (Board)
|
||
|
||
Use the 💡 button to open AI planning mode:
|
||
|
||
- Fusion asks clarifying questions
|
||
- Produces a structured summary
|
||
- Lets you create one task or break into multiple dependency-linked tasks
|
||
|
||
### Option C: Subtask Breakdown (Board)
|
||
|
||
Use the 🌳 button to:
|
||
|
||
- Generate 2–5 subtasks
|
||
- Reorder by drag-and-drop
|
||
- Add dependency links before creating tasks
|
||
|
||
### Option D: Expanded Controls (Board)
|
||
|
||
Expand the quick entry panel (▼) to access additional controls:
|
||
|
||
- **Refine** (✨) — Improve the description with AI
|
||
- **Deps** (🔗) — Link existing tasks as dependencies
|
||
- **Attach** — Add image attachments
|
||
- **Models** (🧠) — Set per-task model overrides
|
||
- **Agent** — Assign an agent to the task
|
||
- **Save** — Create the task manually
|
||
|
||
### Option E: CLI
|
||
|
||
```bash
|
||
fn task create "Fix flaky login test"
|
||
fn task plan "Implement role-based access control"
|
||
```
|
||
|
||
## Understand the Task Lifecycle
|
||
|
||
Fusion uses six columns:
|
||
|
||
1. **Triage** — raw idea; AI writes spec
|
||
2. **Todo** — specified and queued
|
||
3. **In Progress** — executor implements in a dedicated worktree
|
||
4. **In Review** — implementation complete, awaiting merge/finalization
|
||
5. **Done** — merged and complete
|
||
6. **Archived** — retained for history, optionally cleaned up from filesystem
|
||
|
||
## Daily CLI Commands
|
||
|
||
```bash
|
||
fn task list
|
||
fn task show FN-001
|
||
fn task logs FN-001 --follow --limit 50
|
||
fn task steer FN-001 "Prefer existing utility functions"
|
||
fn task pause FN-001
|
||
fn task unpause FN-001
|
||
```
|
||
|
||
## Dashboard Orientation (Annotated)
|
||
|
||
|
||
|
||
Suggested way to read the screen:
|
||
|
||
- **Top bar:** global actions (settings, activity, mission/agent tools)
|
||
- **Columns:** task lifecycle stages
|
||
- **Task cards:** status, metadata, PR/issue badges
|
||
- **Quick entry:** fastest way to create a new task
|
||
|
||
Next: [Architecture](./architecture.md) for internals, or [Task Management](./task-management.md) for deeper task workflows.
|