fusion/docs/dashboard-guide.md

Dashboard Guide

← Docs index

The Fusion dashboard is the main control plane for tasks, agents, missions, settings, logs, and repository operations.

Board View

Board view is the kanban surface for day-to-day operation.

Features:

• Drag-and-drop between lifecycle columns
• Search/filter tasks
• Column visibility controls
• Inline quick entry creation
• PR/issue badges with live updates

List View

List view is optimized for dense task management.

Features:

• Sectioned task table grouped by lifecycle column
• Sortable columns (ID/title/status/column)
• Column visibility toggles and optional hide-done filtering
• Bulk selection + batch model updates

Chat View

Chat view provides project-scoped conversations with agents.

Quick Chat

Quick Chat is an optional floating panel for fast, project-scoped assistant conversations without leaving your current view.

• Controlled by the project setting showQuickChatFAB
• Supports agent mentions (@agent) and file mentions
• Uses the same model/provider infrastructure as full Chat view

Mailbox View

Mailbox view shows inbox/outbox communication threads and unread state.

Interactive Terminal

Fusion embeds a terminal using xterm.js.

Features:

• Multiple terminal tabs
• PTY-backed shell sessions
• Mobile-aware virtual keyboard handling and auto-refit behavior

Git Manager

Git manager centralizes repo operations in the dashboard.

Features:

• Branch/worktree visibility
• Commit and diff browsing
• Push/pull/fetch actions
• Remote editing controls

Documents View

Documents view aggregates task documents and project markdown files.

Features:

• Group task documents by task ID (with revision history metadata)
• Search documents across tasks
• Open project markdown files with inline preview
• Jump directly from a document group to the owning task detail modal

File Browser and Editor Tools

Fusion also includes file browsing/editing tools (for project root and task worktrees) in file/terminal workflows, so you can inspect generated artifacts and make targeted edits without leaving the dashboard.

Activity Log

The activity log tracks task/system events over time.

Features:

• Event type filtering
• Auto-refresh updates
• Operational traceability for the current ActivityEventType set:
  • task:created
  • task:moved
  • task:updated
  • task:deleted
  • task:merged
  • task:failed
  • settings:updated

Theme System

Visual customization includes:

• Theme mode: dark/light/system
• 54 color themes (including Ocean, Forest, Nord, Dracula, Gruvbox, Tokyo Night, and more)

Theme preferences are stored in global settings.

Usage Dialog

Usage view shows provider consumption and limits.

Features:

• Progress bars by provider/model
• Reset window visibility
• Helps diagnose capacity/rate-limit conditions

Spec Editor

The spec editor lets you edit PROMPT.md directly.

Features:

• Manual prompt edits
• AI revision requests
• Rebuild/regenerate flows when task intent changes

Planning Mode

Planning mode is an AI interview workflow for shaping task scope.

Features:

• Clarification Q&A
• Summary generation
• Two final actions: Create Task or Break into Tasks
• Multi-task creation uses key deliverables and dependency linking

Session Lifecycle

• Send to Background — Hides the modal but preserves the session server-side. The session continues running and can be resumed from the Background Sessions panel.
• Close (X button or Escape) — Explicitly abandons the session on the server. The AI stops processing and the session is terminated. Use this when you want to cancel without saving progress.
• Session Persistence — Planning sessions that are actively running (generating, awaiting input, complete, or error) appear in the Background Sessions panel and can be resumed.

Subtask Breakdown Dialog

The subtask dialog supports structured decomposition before creation.

Features:

• AI-generated subtasks
• Drag-and-drop reordering
• Keyboard reordering controls
• Dependency linking constrained to earlier items

Session Lifecycle

• Send to Background — Hides the modal but preserves the session server-side. The session continues running and can be resumed from the Background Sessions panel.
• Close (X button or Cancel) — Explicitly abandons the session on the server. The AI stops processing and the session is terminated. Confirmation is shown if there are unsaved changes.

Settings Modal

Central place for model/provider config, execution behavior, notifications, backups, and UI preferences.

Workflow Step Manager

Create and manage reusable quality gates for tasks.

Agents View

Inspect agents, runtime status, run history, and configuration.

Agent Skill Assignment

Agents can be assigned skills that determine which capabilities are injected into their sessions at execution time. Skills are configured via the agent's metadata.skills field (an array of requested skill names).

You can set metadata.skills in two ways:

• Dashboard: Edit an agent and add or update the skills key in its metadata JSON.
• Import: When importing agents from YAML, the skills list is mapped to metadata.skills automatically.

During task execution, the engine's buildSessionSkillContext reads metadata.skills from the assigned agent. If valid skills are present, they take precedence over the default role fallback skills (e.g., executor, reviewer, merger, triage). If no skills are assigned, the engine falls back to the standard role-based skill mapping.

Mission Manager

Manage mission hierarchy and progression state.

Roadmaps View

Roadmaps provide a dedicated planning surface for organizing product development with hierarchical milestones and features.

Available when the experimentalFeatures.roadmap toggle is enabled.

Creating Roadmaps

1. Click the + button in the Roadmaps sidebar to create a new roadmap
2. Enter a title and optional description
3. Click Create to save

Managing Milestones

• Click + Add Milestone to add milestones to the selected roadmap
• Click the pencil icon to edit a milestone title inline (Enter to save, Escape to cancel)
• Click the trash icon to delete a milestone (requires confirmation)

Managing Features

• Click + Add Feature within a milestone card to add features
• Features are displayed in a scrollable list within each milestone
• Hover over a feature to reveal edit and delete actions
• Click the pencil icon to edit a feature title inline
• Click the trash icon to delete a feature (requires confirmation)

Roadmap Drag-and-Drop Ordering

Milestones and features can be reordered using native drag-and-drop:

Milestone Reordering:

• Drag a milestone by its grip handle on the left side of the milestone card
• Drop it before or after other milestones to reorder
• The new order is persisted immediately

Feature Reordering:

• Drag a feature by its grip handle on the left side of the feature row
• Drop before or after other features within the same milestone to reorder
• The new order is persisted immediately

Cross-Milestone Moves:

• Drag a feature and drop it into a different milestone card
• The feature is moved to the new milestone at the drop position
• Empty milestone areas also accept drops (appends to end)

Visual Feedback:

• Dragging items show reduced opacity
• Drop targets highlight with a blue border
• Drop position indicators show before/after placement with blue lines

Roadmap Actions

• Click a roadmap in the sidebar to view its milestones and features
• Use the header buttons to edit or delete the selected roadmap
• Delete requires confirmation and removes all associated milestones and features

AI Milestone Suggestions

Roadmaps View includes one-click AI-powered milestone generation to help you quickly create milestone ideas from a goal prompt.

How to use:

1. Select a roadmap from the sidebar
2. In the "Generate Milestone Ideas" section, describe your roadmap goal in the text area
3. Click Generate Milestones to create AI suggestions
4. Review the suggested milestones:
   • Click the pencil icon to edit a suggestion before accepting
   • Click the check icon on any suggestion to accept it as a milestone
   • Click Accept All to add all suggestions as milestones (in order)
   • Click the X button to clear all suggestions

Editing Suggestions:

• Click the pencil icon on any suggestion to open the inline editor
• Modify the title and/or description
• Click check to save your changes or X to cancel
• Changes are reflected immediately and used when accepting

Key features:

• Suggestions are generated using AI and include both titles and descriptions
• Suggestions are editable before acceptance - click the pencil icon to modify
• Empty or whitespace-only titles are not accepted (validation enforced)
• Accepted milestones appear immediately in your roadmap
• Milestones are created in the order displayed in the suggestion list
• Suggestions are ephemeral (in-memory only) and don't persist to the database
• The generate button is disabled when no roadmap is selected or prompt is empty

AI Feature Suggestions

Within each milestone, you can generate AI-powered feature suggestions to quickly add features.

How to use:

1. Open a roadmap and select it
2. Find the milestone you want to add features to
3. Click the AI Suggestions button in the milestone's action bar
4. Review the suggested features:
   • Click the pencil icon to edit a suggestion before accepting
   • Click the check icon on any suggestion to accept it as a feature
   • Click Accept All to add all suggestions as features (in order)
   • Click Clear to discard all suggestions

Editing Suggestions:

• Click the pencil icon on any feature suggestion to open the inline editor
• Modify the title and/or description
• Click check to save your changes or X to cancel
• Changes are reflected immediately and used when accepting

Key features:

• Features are generated using AI based on the milestone's context
• Suggestions include existing features to avoid duplication
• Suggestions are editable before acceptance - click the pencil icon to modify
• Empty or whitespace-only titles are not accepted (validation enforced)
• Accepted features appear immediately in the milestone
• Features are created in the order displayed in the suggestion list
• Suggestion state is scoped to each milestone (no cross-milestone leakage)
• The AI Suggestions button shows "Generating..." while a request is in flight

Empty States

• No roadmaps: "No roadmaps yet. Click + to create one."
• No milestones: "This roadmap has no milestones. Click + on a milestone lane to add one."
• No features: "No features yet." displayed within each milestone card

Roadmap Export / Handoff

Roadmaps can be exported as structured data for use in mission and task planning flows.

How to use:

1. Hover over a roadmap in the sidebar
2. Click the download icon (↘) to open the export modal
3. Click Load Handoff Data to fetch the roadmap's handoff payload
4. Review the exported data:
   • Mission Planning Handoff: Roadmap structure with milestones and features in deterministic order
   • Feature Task Handoffs: Individual feature entries with source lineage (roadmap ID, milestone ID, feature ID, titles, and order indices)

Key features:

• This is a read-only export — no missions, slices, or tasks are created
• The handoff preserves source lineage for traceability to the original roadmap
• Ordering is deterministic (milestone order, then feature order)
• Click Copy to Clipboard to copy the full handoff payload as JSON
• Handoff data can be manually used to seed mission planning prompts or task creation flows

Use cases:

• Export a roadmap's milestone/feature structure to guide AI-assisted mission planning
• Copy individual feature handoffs as task planning prompts
• Preserve roadmap context when creating tasks in the task board

Memory View

Memory view provides a multi-file editor for project and daily memory files.

Available when the experimentalFeatures.memoryView toggle is enabled.

Task Detail Modal

Inspect task definition, logs, comments, documents, workflow outcomes, and model overrides from a single modal.

Node Dashboard

The Node Dashboard provides a mesh view of connected Fusion nodes. Each node can be a local instance or a remote headless node (fn serve).

Local/Remote Node Switching

When remote nodes are available, the dashboard header displays a node status indicator:

• Local mode — Shows a green "Local" badge, indicating the dashboard is connected to the local Fusion instance
• Remote mode — Shows the remote node name with its connection status (online/offline/connecting)

Click the chevron next to the status indicator to open the node selector dropdown:

• Local — Switch back to viewing the local Fusion instance
• Remote nodes — Select a remote node to view its tasks, projects, and status

How Node Switching Works

1. The node selector appears in the header when remote nodes are registered in the mesh
2. Selecting a remote node routes all API calls through the proxy endpoint (/api/proxy/:nodeId/...)
3. Task data (projects, tasks) is fetched from the remote node and displayed in the dashboard
4. SSE events from the remote node are streamed via the proxy and update the dashboard in real-time
5. Selecting "Local" returns to the local Fusion instance with full local data

Benefits of Remote Node Viewing

• Monitor task progress across distributed teams
• View task status on remote headless nodes without direct SSH access
• Compare project health across multiple Fusion instances
• Stay informed about remote agent activity and task completion

Node Status Indicators

Status	Color	Meaning
Online	Green	Node is connected and responsive
Offline	Red	Node is unreachable or shut down
Connecting	Yellow (pulsing)	Connection attempt in progress

Persistence

The selected node persists across browser sessions via localStorage. If the selected remote node is unregistered, the dashboard automatically falls back to local mode.

Skills API

The Skills API provides endpoints for managing execution skills. Skills are toggled via project-scoped settings in .fusion/settings.json.

GET /api/skills/discovered

List all discovered skills with their enabled state.

Response: 200 OK

{
  "skills": [
    {
      "id": "npm%3A%40example%2Fskill::skills/foo/SKILL.md",
      "name": "foo/SKILL.md",
      "path": "/path/to/skills/foo/SKILL.md",
      "relativePath": "skills/foo/SKILL.md",
      "enabled": true,
      "metadata": {
        "source": "npm:@example/skill",
        "scope": "project",
        "origin": "package"
      }
    }
  ]
}

Skill ID Format: encodeURIComponent(metadata.source) + "::" + relativePath

• Top-level skills use source: "*"
• Package skills use the package source identifier

Error Response: 404 Not Found

{
  "error": "Skills adapter not configured",
  "code": "adapter_not_configured"
}

GET /api/skills/:id/content

Fetch a skill's SKILL.md content and supplementary file metadata.

Response: 200 OK

{
  "content": {
    "name": "foo/SKILL.md",
    "skillMd": "# Foo Skill\n...",
    "files": [
      {
        "name": "examples",
        "relativePath": "skills/foo/examples",
        "type": "directory"
      },
      {
        "name": "example.ts",
        "relativePath": "skills/foo/examples/example.ts",
        "type": "file"
      }
    ]
  }
}

Error Responses:

• 400 Bad Request — invalid encoded skill ID (code: "invalid_skill_id")
• 404 Not Found — skill not found (code: "skill_not_found") or adapter missing (code: "adapter_not_configured")

PATCH /api/skills/execution

Toggle a skill's enabled/disabled state.

Request Body:

{
  "skillId": "npm%3A%40example%2Fskill::skills/foo/SKILL.md",
  "enabled": true
}

Response: 200 OK

{
  "success": true,
  "skillId": "npm%3A%40example%2Fskill::skills/foo/SKILL.md",
  "enabled": true,
  "persistence": {
    "scope": "project",
    "targetFile": "/path/to/.fusion/settings.json",
    "settingsPath": "packages[].skills",
    "pattern": "+skills/foo/SKILL.md"
  }
}

Toggle Semantics:

• Top-level skills (origin: "top-level"): Mutate settings.skills
  • Enable: ensures +<relativePath> exists, removes -<relativePath>
  • Disable: ensures -<relativePath> exists, removes +<relativePath>
• Package skills (origin: "package"): Mutate settings.packages[].skills for the matching metadata.source
  • If the package entry is a string, it's converted to an object { source: <same>, skills: [] }
  • Other package fields (extensions, prompts, themes) are preserved

Error Responses:

• 400 Bad Request — Invalid request body

  { "error": "skillId is required", "code": "invalid_body" }
  

• 404 Not Found — Adapter not configured

  { "error": "Skills adapter not configured", "code": "adapter_not_configured" }
  

GET /api/skills/catalog

Fetch the skills.sh catalog with optional authentication.

Query Parameters:

• limit (optional): Number of results (default 20, max 100)
• q (optional): Search query string

Response: 200 OK

{
  "entries": [
    {
      "id": "example-skill",
      "slug": "example-skill",
      "name": "Example Skill",
      "description": "An example skill",
      "tags": ["utility"],
      "installs": 100,
      "installation": {
        "installed": true,
        "matchingSkillIds": ["npm%3A%40example%2Fskill::skills/example/SKILL.md"],
        "matchingPaths": ["skills/example/SKILL.md"]
      }
    }
  ],
  "auth": {
    "mode": "unauthenticated",
    "tokenPresent": false,
    "fallbackUsed": false
  }
}

Authentication Flow:

1. If SKILLS_SH_TOKEN env var is present, use authenticated request
2. If authenticated request returns 401/403, retry without authentication (fallback mode)
3. If no token, use unauthenticated request directly

Auth Mode Values:

• authenticated — Request made with token
• unauthenticated — Request made without token (no token available)
• fallback-unauthenticated — Initial authenticated request failed with 401/403, retried without token

Error Response: 502 Bad Gateway

{
  "error": "Upstream request timed out",
  "code": "upstream_timeout"
}

Possible error codes:

• upstream_timeout — Request timed out
• upstream_http_error — Upstream returned an error status
• upstream_invalid_payload — Upstream returned invalid response format