docs(FN-1158): add comprehensive project documentation suite

- Add docs index with structured navigation and links across the new documentation set
- Document onboarding and technical foundations with getting-started and architecture guides
- Add detailed CLI and settings references plus feature guides for dashboard, tasks, workflow steps, missions, multi-project, and agents
- Add a contributing guide and polish cross-references between docs pages for discoverability
- Include dashboard screenshots for key views to provide visual context in the guides

docs/README.md

@@ -0,0 +1,44 @@
+# Fusion Documentation
+
+[← Back to repository root](../README.md)
+
+Fusion is an AI-orchestrated task board that turns ideas into reviewed, merged code using a structured workflow: **triage → todo → in-progress → in-review → done**.
+
+![Fusion Dashboard Overview](screenshots/dashboard-overview.png)
+
+## Quick Start
+
+Install Fusion globally, run `fn dashboard`, then create your first task from the board or CLI.
+
+For a full walkthrough (installation, onboarding, first task, and lifecycle), start here:
+
+➡️ **[Getting Started](./getting-started.md)**
+
+## Documentation Index
+
+| Guide | What it covers |
+|---|---|
+| [Getting Started](./getting-started.md) | Installation, first-run onboarding, first task, and daily workflow basics. |
+| [Architecture](./architecture.md) | System architecture, package layout, storage model, and engine execution flow. |
+| [CLI Reference](./cli-reference.md) | Complete `fn` command reference with subcommands, flags, and examples. |
+| [Dashboard Guide](./dashboard-guide.md) | Detailed guide to board/list views, terminal, git manager, files, planning, and UI tools. |
+| [Task Management](./task-management.md) | Task creation modes, lifecycle, prompt specs, comments, archiving, and GitHub integration. |
+| [Missions](./missions.md) | Mission hierarchy, planning flow, activation, progress tracking, and autopilot behavior. |
+| [Agents](./agents.md) | Agent management, presets, prompts, heartbeat behavior, spawning, and mailbox workflows. |
+| [Workflow Steps](./workflow-steps.md) | Reusable quality gates, templates, pre/post-merge phases, and workflow execution results. |
+| [Settings Reference](./settings-reference.md) | Global and project settings, defaults, API endpoints, and model selection hierarchy. |
+| [Multi-Project](./multi-project.md) | Central registry architecture, project management, isolation modes, and migration paths. |
+| [Contributing](./contributing.md) | Local development setup, testing, release flow, and contributor conventions. |
+| [Code Signing Setup](./CODE_SIGNING.md) | macOS and Windows code signing configuration for release binaries. |
+
+## External Resources
+
+- GitHub repository: https://github.com/gsxdsm/fusion
+- npm package: https://www.npmjs.com/package/@gsxdsm/fusion
+- pi agent framework: https://github.com/badlogic/pi-mono
+
+## Suggested Reading Paths
+
+- **New user:** Getting Started → Dashboard Guide → Task Management
+- **Power user / automation owner:** Settings Reference → Workflow Steps → Agents
+- **Maintainer / contributor:** Architecture → Multi-Project → Contributing

docs/agents.md

@@ -0,0 +1,92 @@
+# Agents
+
+[← Docs index](./README.md)
+
+Fusion uses multiple agent roles for triage, execution, review, and merge workflows.
+
+## Agents View (Dashboard)
+
+The agents surface provides:
+
+- Agent list and status
+- Detail/config panels
+- Runtime metrics
+- Run history
+- Task assignment context
+
+![Agents view](./screenshots/agents-view.png)
+
+## Built-In Agent Prompt Templates
+
+Fusion includes built-in templates for role prompts:
+
+- `default-executor`
+- `default-triage`
+- `default-reviewer`
+- `default-merger`
+- `senior-engineer`
+- `strict-reviewer`
+- `concise-triage`
+
+These can be assigned per role using `agentPrompts.roleAssignments`.
+
+## Per-Agent Configuration
+
+Agents can be configured with:
+
+- Custom instructions
+- Heartbeat interval/timeout limits
+- Max concurrent heartbeat runs
+
+Heartbeat values are validated and minimum-clamped.
+
+## Configurable Agent Prompts (`agentPrompts`)
+
+`agentPrompts` project setting supports:
+
+- `templates[]`: custom prompt templates by role
+- `roleAssignments`: map role → template ID
+
+When no assignment is configured, Fusion falls back to built-in defaults.
+
+## Inter-Agent Messaging
+
+Messaging is available in dashboard mailbox UI and CLI.
+
+```bash
+fn message inbox
+fn message outbox
+fn message send AGENT-001 "Please prioritize FN-420"
+fn message read MSG-123
+fn message delete MSG-123
+fn agent mailbox AGENT-001
+```
+
+## Agent Spawning
+
+Executor sessions can spawn child agents through `spawn_agent`.
+
+Behavior:
+
+- Child agents run in separate worktrees
+- Parent/child relationship is tracked
+- Limits enforced:
+  - `maxSpawnedAgentsPerParent` (default 5)
+  - `maxSpawnedAgentsGlobal` (default 20)
+- Child sessions terminate when parent task ends
+
+## Heartbeat Monitoring and Trigger Scheduling
+
+Fusion’s `HeartbeatTriggerScheduler` supports three trigger types:
+
+- `timer` — periodic wake based on heartbeat interval
+- `assignment` — wake when task is assigned to agent
+- `on_demand` — manual run trigger (`POST /api/agents/:id/runs`)
+
+All triggers respect per-agent `maxConcurrentRuns` and produce structured wake context metadata.
+
+## Related Docs
+
+- [Workflow Steps](./workflow-steps.md)
+- [Settings Reference](./settings-reference.md)
+- [Architecture](./architecture.md)

docs/architecture.md

@@ -0,0 +1,125 @@
+# Architecture
+
+[← Docs index](./README.md)
+
+This document explains how Fusion is structured, how data is stored, and how the AI execution pipeline moves work from idea to merged code.
+
+## End-to-End Workflow
+
+```mermaid
+graph TD
+    H((You)) -->|rough idea| T["Triage\n<i>auto-specification</i>"]
+    T --> TD["Todo\n<i>scheduled for execution</i>"]
+    TD --> IP["In Progress\n<i>plan, review, execute, review</i>"]
+
+    IP --> IR["In Review\n<i>ready to merge</i>"]
+    IR --> D["Done"]
+```
+
+At a high level:
+
+- **Triage** writes a full `PROMPT.md` spec
+- **Scheduler** selects ready tasks (respecting dependencies and limits)
+- **Executor** runs agents in isolated worktrees
+- **Merger** finalizes tasks to `done` (direct squash merge or PR flow)
+
+## Workspace Packages
+
+| Package | Responsibility |
+|---|---|
+| `@fusion/core` | Domain model, TaskStore/MissionStore, SQLite persistence, shared types/defaults. |
+| `@fusion/dashboard` | Express API + React dashboard UI (kanban board, live updates, tooling surfaces). |
+| `@fusion/engine` | Triage, scheduling, execution, workflow steps, merge orchestration, automation runtime. |
+| `@fusion/tui` | Ink-based terminal UI package (lightweight terminal components). |
+| `@gsxdsm/fusion` | Published CLI (`fn`) + pi extension tools. |
+
+## Storage Architecture
+
+Fusion uses a **hybrid model**:
+
+- **SQLite metadata:** `.fusion/fusion.db`
+- **Blob/filesystem artifacts:** `.fusion/tasks/{id}/PROMPT.md`, `agent.log`, attachments
+- **Global user settings:** `~/.pi/fusion/settings.json`
+
+### Why hybrid?
+
+- SQLite gives transactional metadata updates and indexed queries.
+- Filesystem storage keeps large task artifacts simple and portable.
+
+### Key SQLite behavior
+
+- WAL mode enabled for concurrent readers/writers
+- Foreign keys enforced
+- Monotonic metadata timestamp used for change detection
+
+## Typical `.fusion/` Layout
+
+```text
+.fusion/
+  fusion.db
+  tasks/
+    FN-001/
+      task.json
+      PROMPT.md
+      agent.log
+      attachments/
+  backups/
+```
+
+## AI Engine Components
+
+### 1) TriageProcessor
+
+- Reads rough task descriptions
+- Generates structured `PROMPT.md` with mission, file scope, steps, and acceptance criteria
+- Can be gated by `requirePlanApproval`
+
+### 2) Scheduler
+
+- Moves tasks from `todo` to `in-progress`
+- Enforces dependencies, concurrency limits, and overlap rules
+- Coordinates mission/slice progression hooks
+
+### 3) TaskExecutor
+
+- Creates/attaches task worktrees (`fusion/{task-id}` branches)
+- Runs agent sessions with tooling (task update/logging/review/spawn)
+- Supports step session mode (`runStepsInNewSessions`) and parallel step execution (`maxParallelSteps`)
+- Executes configured pre-merge workflow steps
+
+## Error Recovery and Resilience
+
+Fusion has multiple safety/recovery paths:
+
+- **Transient error retry:** bounded retry flow for temporary failures
+- **Stuck task detection:** inactivity timeout can terminate/requeue hung runs
+- **Context-limit recovery:** compact-and-resume flow when model context overflows
+- **Workflow step failure handling:** marks task failed/in-review for inspection rather than silently passing
+- **Pause semantics:** global hard-stop (`globalPause`) and soft scheduler pause (`enginePaused`)
+
+## Project Memory System
+
+When enabled (`memoryEnabled: true`), agents can use project memory files:
+
+- `.fusion/memory.md` — durable project learnings
+- Optional derived memory insights (via scheduled extraction)
+
+This helps agents retain patterns and pitfalls across tasks.
+
+## Git Worktree Isolation Model
+
+Every active task runs in its own git worktree:
+
+- Avoids cross-task file collisions
+- Makes cleanup/retry deterministic
+- Enables parallel execution safely
+- Supports pooled reuse when `recycleWorktrees` is enabled
+
+Branch naming remains `fusion/{task-id}` regardless of worktree folder naming mode.
+
+## Related Guides
+
+- [Task Management](./task-management.md)
+- [Workflow Steps](./workflow-steps.md)
+- [Multi-Project](./multi-project.md)
+- [Settings Reference](./settings-reference.md)

docs/cli-reference.md

@@ -0,0 +1,251 @@
+# CLI Reference
+
+[← Docs index](./README.md)
+
+Fusion’s command-line interface is exposed through the `fn` command.
+
+## Global Usage
+
+```bash
+fn <command> <subcommand> [options]
+```
+
+### Global options
+
+| Option | Description |
+|---|---|
+| `--project <name>`, `-P <name>` | Target a specific registered project. |
+| `--help`, `-h` | Show help output. |
+
+### Project resolution order
+
+When `--project` is not supplied, Fusion resolves project context in this order:
+
+1. Explicit `--project` flag
+2. Default project (set via `fn project set-default <name>`)
+3. Current-directory auto-detection (`.fusion/fusion.db` lookup upward)
+
+---
+
+## `fn init`
+
+Initialize a new Fusion project in the current directory.
+
+```bash
+fn init
+fn init --name my-project --path /absolute/path/to/project
+```
+
+---
+
+## `fn dashboard`
+
+Start the web dashboard (default port `4040`).
+
+```bash
+fn dashboard
+fn dashboard --port 5050
+fn dashboard --interactive
+fn dashboard --paused
+fn dashboard --dev
+```
+
+---
+
+## `fn task`
+
+Task lifecycle and task operations.
+
+### Creation and planning
+
+```bash
+fn task create "Fix login race condition"
+fn task create "Fix bug" --attach screenshot.png --depends FN-010
+fn task plan "Design a new authentication flow"
+```
+
+### Query and logs
+
+```bash
+fn task list
+fn task show FN-001
+fn task logs FN-001 --follow --limit 50 --type tool
+```
+
+### Execution and status
+
+```bash
+fn task move FN-001 in-progress
+fn task update FN-001 2 done
+fn task log FN-001 "Updated API contract"
+fn task retry FN-001
+fn task pause FN-001
+fn task unpause FN-001
+```
+
+### Collaboration and guidance
+
+```bash
+fn task comment FN-001 "Needs stricter validation"
+fn task comment FN-001 "Reviewed with QA" --author "alex"
+fn task comments FN-001
+fn task steer FN-001 "Reuse existing auth middleware"
+```
+
+### Completion, maintenance, and history
+
+```bash
+fn task attach FN-001 ./trace.log
+fn task merge FN-001
+fn task duplicate FN-001
+fn task refine FN-001 --feedback "Add rollback handling"
+fn task archive FN-001
+fn task unarchive FN-001
+fn task delete FN-001 --force
+```
+
+### GitHub integration
+
+```bash
+fn task pr-create FN-001 --title "Fix login race" --base main
+fn task import owner/repo --labels bug --limit 10
+fn task import owner/repo --interactive
+```
+
+---
+
+## `fn project`
+
+Manage registered projects in multi-project mode.
+
+```bash
+fn project list --json
+fn project add my-app /path/to/app --isolation child-process
+fn project show my-app
+fn project info my-app
+fn project set-default my-app
+fn project detect
+fn project remove my-app --force
+```
+
+Subcommands: `list|ls`, `add`, `remove|rm`, `show`, `info`, `set-default|default`, `detect`.
+
+---
+
+## `fn node`
+
+Manage external execution nodes.
+
+```bash
+fn node list --json
+fn node add edge-runner --url https://node.example.com --api-key $NODE_API_KEY --max-concurrent 4
+fn node show edge-runner
+fn node health edge-runner
+fn node remove edge-runner --force
+```
+
+Subcommands: `list|ls`, `add`, `remove|rm`, `show|info`, `health`.
+
+---
+
+## `fn mission`
+
+Mission hierarchy operations.
+
+```bash
+fn mission create "Platform hardening" "Security and reliability initiative"
+fn mission list
+fn mission show mission_123
+fn mission delete mission_123 --force
+fn mission activate-slice slice_456
+```
+
+Subcommands: `create`, `list|ls`, `show|info`, `delete`, `activate-slice`.
+
+---
+
+## `fn agent`
+
+Agent runtime operations.
+
+```bash
+fn agent stop AGENT-001
+fn agent start AGENT-001
+fn agent mailbox AGENT-001
+fn agent import ./companies-manifest.yaml --dry-run
+```
+
+Subcommands: `stop`, `start`, `mailbox`, `import`.
+
+---
+
+## `fn message`
+
+Inter-agent/user message mailbox.
+
+```bash
+fn message inbox
+fn message outbox
+fn message send AGENT-001 "Please prioritize FN-222"
+fn message read MSG-123
+fn message delete MSG-123
+```
+
+---
+
+## `fn settings`
+
+Show and manage settings.
+
+```bash
+fn settings
+fn settings set maxConcurrent 4
+fn settings export --scope both
+fn settings import fusion-settings.json --yes
+```
+
+---
+
+## `fn git`
+
+Project git operations.
+
+```bash
+fn git status
+fn git fetch
+fn git fetch upstream
+fn git pull --yes
+fn git push --yes
+```
+
+---
+
+## `fn backup`
+
+Database backup lifecycle.
+
+```bash
+fn backup --create
+fn backup --list
+fn backup --restore .fusion/backups/fusion-2026-04-08.db
+fn backup --cleanup
+```
+
+---
+
+## Useful option flags by context
+
+| Option | Used by |
+|---|---|
+| `--port`, `-p` | `fn dashboard` |
+| `--interactive` | `fn dashboard`, `fn task import`, `fn project add` |
+| `--paused` | `fn dashboard` |
+| `--dev` | `fn dashboard` |
+| `--attach` | `fn task create` |
+| `--depends` | `fn task create` |
+| `--feedback` | `fn task refine` |
+| `--yes` | confirmation-skipping flows (`task plan`, `settings import`, git pull/push, etc.) |
+| `--limit`, `-l` | `fn task import` |
+| `--labels`, `-L` | `fn task import` |
+
+For configuration details used by these commands, see [Settings Reference](./settings-reference.md).

docs/contributing.md

@@ -0,0 +1,107 @@
+# Contributing
+
+[← Docs index](./README.md)
+
+Thanks for contributing to Fusion.
+
+## Development Setup
+
+### Prerequisites
+
+- Node.js (current LTS recommended)
+- pnpm (`packageManager` is pnpm)
+- Git
+- `pi` runtime/auth configured for AI features
+
+### Install dependencies
+
+```bash
+pnpm install
+```
+
+### Build all packages
+
+```bash
+pnpm build
+```
+
+## Workspace Package Overview
+
+| Package | Purpose |
+|---|---|
+| `@fusion/core` | Shared domain types, stores, persistence, and core utilities |
+| `@fusion/dashboard` | Express API + React UI |
+| `@fusion/engine` | Scheduling, triage, execution, merge orchestration |
+| `@fusion/tui` | Ink-based terminal UI components |
+| `@gsxdsm/fusion` | Published CLI + pi extension |
+
+## Development Workflow
+
+```bash
+pnpm dev          # build + run CLI entrypoint in dev mode
+pnpm dev:ui       # dashboard dev server only
+pnpm typecheck    # workspace typechecks
+pnpm test         # workspace test suite
+pnpm build        # workspace builds
+```
+
+## Testing Requirements
+
+Use real test runs (not manual verification substitutes):
+
+```bash
+pnpm test
+pnpm test:coverage
+pnpm test:coverage:core
+pnpm test:coverage:engine
+pnpm test:coverage:cli
+pnpm test:coverage:dashboard
+```
+
+## Build Standalone Executables
+
+Fusion supports standalone binary builds through Bun compile scripts in the CLI package.
+
+```bash
+pnpm build:exe      # build host-target executable
+pnpm build:exe:all  # build multi-target executables
+```
+
+## Release Process
+
+Fusion uses Changesets + version PR workflow.
+
+- See [RELEASING.md](../RELEASING.md) for release flow details.
+- For published package behavior changes, include a changeset.
+
+## Code Signing
+
+Release binary signing setup is documented here:
+
+- [Code Signing Setup](./CODE_SIGNING.md)
+
+## Git / Commit Conventions
+
+Use task-ID-scoped conventional commits:
+
+- `feat(FN-XXX): ...`
+- `fix(FN-XXX): ...`
+- `test(FN-XXX): ...`
+- `docs(FN-XXX): ...` (for documentation-only changes)
+
+## Project Memory
+
+When enabled, agents can read/write durable project memory:
+
+- `.fusion/memory.md`
+
+Use it for reusable patterns, constraints, and pitfalls that should persist across tasks.
+
+## SQLite Test Runner Pitfall
+
+When running engine tests with Vitest and `node:sqlite`, ensure the engine Vitest config uses thread pool mode:
+
+- ✅ `pool: "threads"`
+- ❌ `pool: "vmThreads"`
+
+`node:sqlite` fails under Vitest VM contexts; using threads avoids that failure mode.

docs/dashboard-guide.md

@@ -0,0 +1,156 @@
+# Dashboard Guide
+
+[← Docs index](./README.md)
+
+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
+
+![Board view](./screenshots/dashboard-overview.png)
+
+## List View
+
+List view is optimized for dense task management.
+
+Features:
+
+- Grouping modes (for example by column/size)
+- Inline title editing
+- Duplicate task actions
+- Quick scanning of metadata without card expansion
+
+## 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
+
+![Interactive terminal](./screenshots/terminal.png)
+
+## 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
+
+![Git manager](./screenshots/git-manager.png)
+
+## File Browser and Editor
+
+Built-in file tools allow quick inspection and edits.
+
+Features:
+
+- Browse project root and task worktrees
+- Open files in an editor with syntax highlighting
+- Navigate artifacts generated during task execution
+
+## Activity Log
+
+The activity log tracks task/system events over time.
+
+Features:
+
+- Event type filtering
+- Auto-refresh updates
+- Operational traceability for task moves, merges, settings updates, and errors
+
+## Theme System
+
+Visual customization includes:
+
+- Theme mode: dark/light/system
+- **30 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
+
+## 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
+
+## Settings Modal
+
+Central place for model/provider config, execution behavior, notifications, backups, and UI preferences.
+
+![Settings modal](./screenshots/settings.png)
+
+## Workflow Step Manager
+
+Create and manage reusable quality gates for tasks.
+
+![Workflow step manager](./screenshots/workflow-steps.png)
+
+## Agents View
+
+Inspect agents, runtime status, run history, and configuration.
+
+![Agents view](./screenshots/agents-view.png)
+
+## Mission Manager
+
+Manage mission hierarchy and progression state.
+
+![Mission manager](./screenshots/mission-manager.png)
+
+## Task Detail Modal
+
+Inspect logs, step progress, workflow outcomes, and model overrides.
+
+![Task detail modal](./screenshots/task-detail.png)

docs/getting-started.md

@@ -0,0 +1,133 @@
+# 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 opens the **model onboarding wizard**. It guides you through:
+
+- Choosing one or more AI providers
+- Authenticating providers (OAuth or API key)
+- Selecting a default model
+
+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 --interactive        # choose port interactively
+fn dashboard --paused             # start with automation paused
+fn dashboard --dev                # run UI only (no engine)
+```
+
+Open: `http://localhost:4040`
+
+## 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: 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)
+
+![Dashboard board view with key UI areas](./screenshots/dashboard-overview.png)
+
+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.

docs/missions.md

@@ -0,0 +1,100 @@
+# Missions
+
+[← Docs index](./README.md)
+
+Missions provide structured planning across multiple related tasks.
+
+## Mission Hierarchy
+
+Fusion models delivery as:
+
+**Mission → Milestone → Slice → Feature → Task**
+
+Example:
+
+```text
+Mission: Improve Reliability
+  Milestone: Stabilize execution pipeline
+    Slice: Retry and recovery hardening
+      Feature: Stuck task recovery improvements
+        Task: FN-210
+        Task: FN-214
+```
+
+## Creating Missions
+
+### Dashboard
+
+Use the Mission Manager UI to create missions and build hierarchy interactively.
+
+### CLI
+
+```bash
+fn mission create "Reliability initiative" "Reduce execution failures and improve recovery"
+fn mission list
+fn mission show mission_123
+fn mission activate-slice slice_456
+fn mission delete mission_123 --force
+```
+
+## Mission Interview and Planning Workflow
+
+The dashboard supports mission planning workflows where you can:
+
+- Define mission outcomes
+- Break work into milestones/slices/features
+- Associate features to executable tasks
+- Track progress at each layer
+
+## Slice Activation and Progress
+
+Slices represent staged execution windows.
+
+- Pending slices remain inactive
+- Active slices are currently allowed to progress
+- Completion rolls up through feature → slice → milestone → mission
+
+Manual activation is available through `fn mission activate-slice <slice-id>`.
+
+## Mission Autopilot
+
+When `autopilotEnabled` is on, Fusion can watch completion events and progress missions automatically.
+
+State machine:
+
+- `inactive`
+- `watching`
+- `activating`
+- `completing`
+
+Typical flow:
+
+1. Mission is watched
+2. Task completion updates feature status
+3. If a slice is complete, autopilot activates next pending slice
+4. When milestones are all complete, mission transitions to complete
+
+## `autopilotEnabled` vs `autoAdvance`
+
+- **`autopilotEnabled`**: enables background monitoring/orchestration behavior
+- **`autoAdvance`**: allows automatic slice activation when current slice completes
+
+Combination behavior:
+
+- `autopilotEnabled=true`, `autoAdvance=true` → full autonomous progression
+- `autopilotEnabled=true`, `autoAdvance=false` → monitored mission with manual slice activation
+
+## Autopilot API Endpoints
+
+| Endpoint | Purpose |
+|---|---|
+| `GET /api/missions/:missionId/autopilot` | Get autopilot status for mission |
+| `PATCH /api/missions/:missionId/autopilot` | Enable/disable autopilot (`{ enabled: boolean }`) |
+| `POST /api/missions/:missionId/autopilot/start` | Start watching manually |
+| `POST /api/missions/:missionId/autopilot/stop` | Stop watching manually |
+
+## Screenshot
+
+![Mission manager](./screenshots/mission-manager.png)
+
+See also: [Multi-Project](./multi-project.md) and [Task Management](./task-management.md).

docs/multi-project.md

@@ -0,0 +1,140 @@
+# Multi-Project
+
+[← Docs index](./README.md)
+
+Fusion can coordinate multiple repositories from one installation, with shared visibility and global concurrency control.
+
+## Why Use Multi-Project Mode?
+
+Use multi-project mode when you need to:
+
+- Operate many repos from one dashboard/CLI
+- Standardize settings and workflows across projects
+- Monitor global activity and system-wide execution capacity
+
+## Central Database Architecture
+
+Multi-project metadata is stored in:
+
+`~/.pi/fusion/fusion-central.db`
+
+Core tables:
+
+- `projects`
+- `projectHealth`
+- `centralActivityLog`
+- `globalConcurrency`
+
+Per-project task data remains in each repo’s `.fusion/fusion.db`.
+
+## Registering and Managing Projects
+
+```bash
+fn project add my-app /path/to/app
+fn project list
+fn project show my-app
+fn project set-default my-app
+fn project detect
+fn project remove my-app --force
+```
+
+## `--project` Flag and Resolution
+
+You can target a project explicitly:
+
+```bash
+fn task list --project my-app
+fn task create "Fix oauth callback" --project my-app
+```
+
+Resolution order without `--project`:
+
+1. explicit flag
+2. default project
+3. current-directory auto-detection
+
+## Project Health Tracking
+
+Central health tracking keeps mutable project metrics, including:
+
+- active task counts
+- in-flight agent counts
+- project status (`initializing`, `active`, `paused`, `errored`)
+
+## Global Concurrency Management
+
+A singleton central record enforces system-wide limits so one project cannot monopolize all execution slots.
+
+## Isolation Modes
+
+Projects can run with:
+
+- **`in-process`** (default): low overhead, shared process
+- **`child-process`**: stronger isolation with independent process boundary
+
+## Auto-Migration from Single-Project
+
+On first run after upgrade:
+
+- Existing project databases are detected
+- Projects are registered into central DB automatically
+- Existing single-project workflows continue working
+
+Migration is idempotent and designed to avoid repeated re-registration.
+
+## Rollback Procedure
+
+If central registry behavior needs to be reverted:
+
+1. Delete `~/.pi/fusion/fusion-central.db`
+2. Keep using per-project `.fusion/fusion.db` data
+3. Fusion falls back to legacy/single-project behavior
+4. Re-register projects later with `fn init` / `fn project add`
+
+## Runtime Architecture
+
+### ProjectRuntime interface
+
+Each project runtime supports start/stop/status/metrics and access to scheduler/task store (for in-process mode).
+
+### HybridExecutor
+
+HybridExecutor orchestrates all project runtimes and forwards project-attributed events.
+
+### IPC Protocol (child-process mode)
+
+Host → worker commands include:
+
+- `START_RUNTIME`
+- `STOP_RUNTIME`
+- `GET_STATUS`
+- `GET_METRICS`
+- `PING`
+
+Worker → host events include:
+
+- `TASK_CREATED`
+- `TASK_MOVED`
+- `TASK_UPDATED`
+- `ERROR_EVENT`
+- `HEALTH_CHANGED`
+
+## HybridExecutor Diagram
+
+```mermaid
+flowchart TD
+    HE[HybridExecutor]
+    PM[Project Manager]
+    CC[CentralCore]
+
+    HE --> PM
+    HE --> CC
+
+    PM --> A[Project A Runtime\n(in-process)]
+    PM --> B[Project B Runtime\n(child-process)]
+    PM --> C[Project C Runtime\n(in-process)]
+
+    B --> IPC[IPC Worker Channel]
+```
+
+See also: [Architecture](./architecture.md), [CLI Reference](./cli-reference.md), and [Missions](./missions.md).

docs/settings-reference.md

@@ -0,0 +1,225 @@
+# Settings Reference
+
+[← Docs index](./README.md)
+
+This guide documents Fusion settings from `packages/core/src/types.ts`.
+
+## Settings Scopes
+
+Fusion uses a two-tier settings system:
+
+- **Global settings** (`~/.pi/fusion/settings.json`): user preferences shared across projects
+- **Project settings** (`.fusion/config.json`): execution/runtime behavior for one project
+
+At runtime, settings are merged. **Project settings override global settings** when keys overlap.
+
+## Settings API Endpoints
+
+| Endpoint | Purpose |
+|---|---|
+| `GET /api/settings` | Get merged settings (global + project). |
+| `PUT /api/settings` | Update project settings only. |
+| `GET /api/settings/global` | Get global settings only. |
+| `PUT /api/settings/global` | Update global settings only. |
+| `GET /api/settings/scopes` | Get separated `{ global, project }` view. |
+
+---
+
+## Global Settings
+
+Defaults from `DEFAULT_GLOBAL_SETTINGS`; key scope from `GLOBAL_SETTINGS_KEYS`.
+
+| Setting | Type | Default | Description |
+|---|---|---:|---|
+| `themeMode` | `"dark" \| "light" \| "system"` | `"dark"` | Dashboard theme mode. |
+| `colorTheme` | `string` | `"default"` | Dashboard color theme name. |
+| `defaultProvider` | `string` | `undefined` | Default AI provider. |
+| `defaultModelId` | `string` | `undefined` | Default AI model ID. |
+| `fallbackProvider` | `string` | `undefined` | Fallback provider when primary model is unavailable/rate-limited. |
+| `fallbackModelId` | `string` | `undefined` | Fallback model ID (must pair with `fallbackProvider`). |
+| `defaultThinkingLevel` | `"off" \| "minimal" \| "low" \| "medium" \| "high"` | `undefined` | Default reasoning effort level. |
+| `ntfyEnabled` | `boolean` | `false` | Enable ntfy push notifications. |
+| `ntfyTopic` | `string` | `undefined` | ntfy topic name. |
+| `ntfyEvents` | `("in-review" \| "merged" \| "failed")[]` | `["in-review","merged","failed"]` | Event types that trigger ntfy notifications. |
+| `ntfyDashboardHost` | `string` | `undefined` | Dashboard host used for deep-link URLs in notifications. |
+| `defaultProjectId` | `string` | `undefined` | Default project for multi-project commands. |
+| `openrouterModelSync` | `boolean` | `true` | Sync OpenRouter model catalog into pickers. |
+| `modelOnboardingComplete` | `boolean` | `undefined` | Whether model onboarding has been completed/dismissed. |
+
+### Additional GlobalSettings fields
+
+These exist in the `GlobalSettings` interface but are not listed in `GLOBAL_SETTINGS_KEYS`.
+
+| Setting | Type | Default | Description |
+|---|---|---:|---|
+| `setupComplete` | `boolean` | `undefined` | Marks completion of first-run setup wizard state. |
+| `favoriteProviders` | `string[]` | `undefined` | Pinned provider names shown first in model selectors. |
+| `favoriteModels` | `string[]` | `undefined` | Pinned models in `{provider}/{modelId}` format. |
+
+---
+
+## Project Settings
+
+Defaults from `DEFAULT_PROJECT_SETTINGS`; key scope from `PROJECT_SETTINGS_KEYS`.
+
+| Setting | Type | Default | Description |
+|---|---|---:|---|
+| `globalPause` | `boolean` | `false` | Hard stop: terminate active engine sessions and pause scheduling. |
+| `enginePaused` | `boolean` | `false` | Soft pause: stop dispatching new work but allow active sessions to finish. |
+| `maxConcurrent` | `number` | `2` | Max concurrent AI tasks. |
+| `maxWorktrees` | `number` | `4` | Max git worktrees. |
+| `pollIntervalMs` | `number` | `15000` | Scheduler poll interval (ms). |
+| `groupOverlappingFiles` | `boolean` | `true` | Serialize execution when file scopes overlap. |
+| `autoMerge` | `boolean` | `true` | Auto-finalize tasks from `in-review`. |
+| `mergeStrategy` | `"direct" \| "pull-request"` | `"direct"` | Completion mode (local direct merge or PR-first). |
+| `worktreeInitCommand` | `string` | `undefined` | Shell command run after worktree creation. |
+| `testCommand` | `string` | `undefined` | Custom test command override. |
+| `buildCommand` | `string` | `undefined` | Custom build command override. |
+| `recycleWorktrees` | `boolean` | `false` | Reuse worktrees from a pool for faster startup. |
+| `worktreeNaming` | `"random" \| "task-id" \| "task-title"` | `"random"` | Naming mode for fresh worktree directories. |
+| `taskPrefix` | `string` | `"FN"` | Prefix for generated task IDs. |
+| `includeTaskIdInCommit` | `boolean` | `true` | Include task ID in commit message scope. |
+| `planningProvider` | `string` | `undefined` | AI provider for triage/spec generation. |
+| `planningModelId` | `string` | `undefined` | Model ID for triage/spec generation. |
+| `planningFallbackProvider` | `string` | `undefined` | Fallback provider for planning. |
+| `planningFallbackModelId` | `string` | `undefined` | Fallback model ID for planning. |
+| `validatorProvider` | `string` | `undefined` | AI provider for plan/code review. |
+| `validatorModelId` | `string` | `undefined` | Model ID for plan/code review. |
+| `validatorFallbackProvider` | `string` | `undefined` | Fallback provider for review. |
+| `validatorFallbackModelId` | `string` | `undefined` | Fallback model ID for review. |
+| `modelPresets` | `array` | `[]` | Reusable executor/validator model presets. |
+| `autoSelectModelPreset` | `boolean` | `false` | Auto-select presets by task size. |
+| `defaultPresetBySize` | `object` | `{}` | Mapping for `S`/`M`/`L` → preset ID. |
+| `autoResolveConflicts` | `boolean` | `true` | Enable automatic merge conflict pattern resolution. |
+| `smartConflictResolution` | `boolean` | `true` | Alias/preferred flag for smart merge conflict handling. |
+| `strictScopeEnforcement` | `boolean` | `false` | Block merges on out-of-scope file changes. |
+| `buildRetryCount` | `number` | `0` | Build retry attempts during merge. |
+| `buildTimeoutMs` | `number` | `300000` | Build timeout in ms (5 minutes). |
+| `requirePlanApproval` | `boolean` | `false` | Require manual approval before triage → todo. |
+| `taskStuckTimeoutMs` | `number` | `undefined` | Inactivity timeout for stuck-task recovery. |
+| `autoUnpauseEnabled` | `boolean` | `true` | Auto-unpause after rate-limit-triggered pauses. |
+| `autoUnpauseBaseDelayMs` | `number` | `300000` | Base unpause retry delay in ms (5 min). |
+| `autoUnpauseMaxDelayMs` | `number` | `3600000` | Max unpause delay cap in ms (1 hour). |
+| `maxStuckKills` | `number` | `6` | Max stuck-task terminations before permanent failure. |
+| `maxSpawnedAgentsPerParent` | `number` | `5` | Max child agents per parent. |
+| `maxSpawnedAgentsGlobal` | `number` | `20` | Max total spawned agents in an executor instance. |
+| `maintenanceIntervalMs` | `number` | `900000` | Maintenance interval in ms (15 min). |
+| `autoUpdatePrStatus` | `boolean` | `false` | Auto-refresh PR status badges. |
+| `autoCreatePr` | `boolean` | `false` | Auto-create PRs for completed tasks. |
+| `autoBackupEnabled` | `boolean` | `false` | Enable scheduled DB backups. |
+| `autoBackupSchedule` | `string` | `"0 2 * * *"` | Backup cron schedule. |
+| `autoBackupRetention` | `number` | `7` | Number of backups to keep. |
+| `autoBackupDir` | `string` | `".fusion/backups"` | Relative backup directory path. |
+| `autoSummarizeTitles` | `boolean` | `false` | Auto-generate titles for long untitled task descriptions. |
+| `titleSummarizerProvider` | `string` | `undefined` | AI provider for title summarization. |
+| `titleSummarizerModelId` | `string` | `undefined` | AI model ID for title summarization. |
+| `titleSummarizerFallbackProvider` | `string` | `undefined` | Fallback provider for title summarization. |
+| `titleSummarizerFallbackModelId` | `string` | `undefined` | Fallback model ID for title summarization. |
+| `tokenCap` | `number` | `undefined` | Proactive token threshold for context compaction. |
+| `insightExtractionEnabled` | `boolean` | `false` | Enable scheduled memory insight extraction. |
+| `insightExtractionSchedule` | `string` | `"0 2 * * *"` | Insight extraction cron schedule. |
+| `insightExtractionMinIntervalMs` | `number` | `86400000` | Minimum interval between insight extraction runs (24h). |
+| `memoryEnabled` | `boolean` | `true` | Enable project memory integration. |
+| `runStepsInNewSessions` | `boolean` | `false` | Run each task step in a fresh agent session. |
+| `maxParallelSteps` | `number` | `2` | Max concurrent step sessions (1–4). |
+| `agentPrompts` | `object` | `undefined` | Custom agent prompt templates + role assignments. |
+
+### Additional ProjectSettings fields
+
+These exist in `ProjectSettings` but are not part of `PROJECT_SETTINGS_KEYS`.
+
+| Setting | Type | Default | Description |
+|---|---|---:|---|
+| `scripts` | `Record<string, string>` | `undefined` | Named script map used by script-mode workflow steps and setup hooks. |
+| `setupScript` | `string` | `undefined` | Named script key to run before task execution. |
+
+---
+
+## Model Selection Hierarchy
+
+### Triage/specification model
+
+1. Per-task `planningModelProvider` + `planningModelId`
+2. Global/project `planningProvider` + `planningModelId`
+3. Global `defaultProvider` + `defaultModelId`
+4. Automatic provider/model resolution
+
+### Executor model
+
+1. Per-task `modelProvider` + `modelId`
+2. Global `defaultProvider` + `defaultModelId`
+3. Automatic provider/model resolution
+
+### Reviewer model
+
+1. Per-task `validatorModelProvider` + `validatorModelId`
+2. Global/project `validatorProvider` + `validatorModelId`
+3. Global `defaultProvider` + `defaultModelId`
+4. Automatic provider/model resolution
+
+---
+
+## JSON Examples
+
+### 1) Team baseline for reliable automation
+
+```json
+{
+  "settings": {
+    "maxConcurrent": 3,
+    "maxWorktrees": 6,
+    "mergeStrategy": "direct",
+    "autoResolveConflicts": true,
+    "taskStuckTimeoutMs": 600000,
+    "runStepsInNewSessions": true,
+    "maxParallelSteps": 2
+  }
+}
+```
+
+### 2) Multi-model routing for plan/execute/review
+
+```json
+{
+  "settings": {
+    "defaultProvider": "anthropic",
+    "defaultModelId": "claude-sonnet-4-5",
+    "planningProvider": "openai",
+    "planningModelId": "gpt-4.1",
+    "validatorProvider": "openai",
+    "validatorModelId": "gpt-4o"
+  }
+}
+```
+
+### 3) Size-based preset auto-selection
+
+```json
+{
+  "settings": {
+    "modelPresets": [
+      {
+        "id": "small-fast",
+        "name": "Small / Fast",
+        "executorProvider": "openai",
+        "executorModelId": "gpt-4o-mini"
+      },
+      {
+        "id": "large-deep",
+        "name": "Large / Deep",
+        "executorProvider": "anthropic",
+        "executorModelId": "claude-sonnet-4-5",
+        "validatorProvider": "openai",
+        "validatorModelId": "gpt-4o"
+      }
+    ],
+    "autoSelectModelPreset": true,
+    "defaultPresetBySize": {
+      "S": "small-fast",
+      "L": "large-deep"
+    }
+  }
+}
+```
+
+See also: [Workflow Steps](./workflow-steps.md) for how `scripts` and workflow model overrides are used.

docs/task-management.md

@@ -0,0 +1,204 @@
+# Task Management
+
+[← Docs index](./README.md)
+
+This guide covers task creation, lifecycle behavior, task metadata, and operational workflows.
+
+## Task Creation Options
+
+### 1) Quick Entry (dashboard)
+
+Use the inline input on board/list view:
+
+- Type description
+- Press Enter
+- Task is created in `triage`
+
+### 2) Plan Mode (AI interview)
+
+Use the 💡 button to open planning mode:
+
+- AI asks clarifying questions
+- Produces summary + key deliverables
+- Create one task or **Break into Tasks** (multi-task generation with dependencies)
+
+### 3) Subtask Breakdown Dialog
+
+Use the 🌳 button:
+
+- Generate 2–5 candidate subtasks
+- Drag to reorder
+- Add dependencies only on earlier items
+- Create tasks in one action
+
+### 4) CLI creation
+
+```bash
+fn task create "Fix API timeout handling"
+fn task plan "Implement role-based access control"
+fn task create "Bug" --attach screenshot.png --depends FN-002
+```
+
+## Task Lifecycle
+
+Fusion task columns:
+
+1. **triage** — idea intake; AI writes a full specification
+2. **todo** — ready for scheduling
+3. **in-progress** — executor active in isolated worktree
+4. **in-review** — implementation complete; awaiting finalization
+5. **done** — merged/finalized
+6. **archived** — preserved history, optionally cleaned from filesystem
+
+### Lifecycle commands
+
+```bash
+fn task move FN-001 todo
+fn task merge FN-001
+fn task archive FN-001
+fn task unarchive FN-001
+```
+
+## Task Detail Modal (Dashboard)
+
+The task detail modal exposes multiple tabs:
+
+- **Details** — primary metadata and description
+- **Steps** — progress across plan/implementation steps
+- **Log** — task event history
+- **Changes** — merge diff/change summary
+- **Workflow** — workflow step results (pass/fail/skip)
+- **Comments** — collaboration thread + steering controls
+- **Model** — per-task model overrides and thinking level
+
+## `PROMPT.md` Specification Structure
+
+After triage, each task gets a structured `PROMPT.md` with sections like:
+
+- Mission
+- Dependencies
+- Context to read first
+- File scope
+- Steps
+- Acceptance criteria
+- Guardrails / Do NOT list
+- Build/test/typecheck requirements
+
+This file is the contract for execution and review.
+
+## Task Comments vs Steering Comments
+
+- **Task comments** (`fn task comment`) are general collaboration notes.
+- **Steering comments** (`fn task steer`) are execution guidance for the running agent.
+
+Steering comments can be injected mid-run into active executor sessions.
+
+## Refinement Tasks
+
+`fn task refine <id>` creates a new triage task that depends on the original done/in-review task.
+
+Example:
+
+```bash
+fn task refine FN-042 --feedback "Add explicit rollback tests for partial failure"
+```
+
+Behavior:
+
+- New title format: `Refinement: <source label>`
+- New task depends on source task
+- Created in `triage`
+
+## Archive and Restore
+
+### Archive behavior
+
+- `fn task archive <id>` moves done task to `archived`
+- Cleanup mode can persist compact metadata and remove the task directory
+
+### Cleanup behavior
+
+- Archived entries are persisted as compact archive snapshots (current runtime stores these in SQLite `archivedTasks`; legacy docs may refer to `.fusion/archive.jsonl`)
+- Task directory (`task.json`, `PROMPT.md`, `agent.log`, attachments) can be removed
+
+### Compact archive entry format
+
+Archive entries preserve key metadata needed for restoration, including:
+
+- `id`, `title`, `description`, `column`
+- `dependencies`, `steps`, `currentStep`
+- `size`, `reviewLevel`, `prInfo`, `issueInfo`
+- `attachments` metadata
+- task `log`
+- timestamps (`createdAt`, `updatedAt`, `columnMovedAt`, `archivedAt`)
+- model override fields (`modelProvider`, `modelId`, `validatorModel*`, `planningModel*`)
+
+`agent.log` content is intentionally not preserved in compact archive entries.
+
+### Restore behavior
+
+`fn task unarchive <id>`:
+
+- Restores archive entry if directory is missing
+- Rebuilds `PROMPT.md`
+- Moves task to `done`
+- Logs “Task restored from archive” when recovering from compact archive entry
+
+## GitHub Issue Import and PR Creation
+
+Import issues:
+
+```bash
+fn task import owner/repo --labels bug --limit 20
+fn task import owner/repo --interactive
+```
+
+Create PR for in-review task:
+
+```bash
+fn task pr-create FN-120 --title "Fix flaky auth flow" --base main
+```
+
+## Completion Modes (`mergeStrategy`)
+
+- **`direct`**: local squash-merge flow into target branch
+- **`pull-request`**: PR-first completion flow via GitHub checks/reviews
+
+Configured via settings.
+
+## Per-Task Model Overrides
+
+Each task may override:
+
+- Executor model (`modelProvider` + `modelId`)
+- Validator model (`validatorModelProvider` + `validatorModelId`)
+- Planning model (`planningModelProvider` + `planningModelId`)
+- Thinking level (`off|minimal|low|medium|high`)
+
+Overrides are configured from the task model tab or task creation actions.
+
+## Model Presets and Auto-Selection by Size
+
+Project settings support reusable model presets:
+
+- `modelPresets`
+- `autoSelectModelPreset`
+- `defaultPresetBySize` (`S`, `M`, `L`)
+
+Users can apply presets at task creation; manual model selection can override them.
+
+## AI Title Summarization
+
+When `autoSummarizeTitles` is enabled and a task has a long untitled description, Fusion can auto-generate a concise title.
+
+## Screenshots
+
+### Board/task cards + quick entry
+
+![Task cards and quick entry on board view](./screenshots/dashboard-overview.png)
+
+### Task detail modal
+
+![Task detail modal](./screenshots/task-detail.png)
+
+For UI-level details, see [Dashboard Guide](./dashboard-guide.md).

docs/workflow-steps.md

@@ -0,0 +1,88 @@
+# Workflow Steps
+
+[← Docs index](./README.md)
+
+Workflow steps are reusable quality gates that run around task completion.
+
+## What They Are
+
+A workflow step is a reusable check (AI prompt or script) that can be enabled on tasks.
+
+Common use cases:
+
+- Documentation review
+- QA/test verification
+- Security scanning
+- Performance checks
+- Accessibility checks
+- Browser-level verification
+
+## Execution Phases
+
+Workflow steps run in one of two phases:
+
+- **Pre-merge** (default): runs before merge/finalization; failure blocks completion
+- **Post-merge**: runs after successful merge; failure is logged but non-blocking
+
+## Execution Modes
+
+- **Prompt mode**: starts an AI agent for the step
+- **Script mode**: runs a named script from project settings (`settings.scripts`)
+
+Prompt mode can run with readonly or coding-capable tool access depending on step/template configuration.
+
+## Built-In Templates (6)
+
+Fusion ships six templates:
+
+1. Documentation Review
+2. QA Check
+3. Security Audit
+4. Performance Review
+5. Accessibility Check
+6. Browser Verification
+
+The Browser Verification template uses browser automation style checks and is designed for UI validation flows.
+
+## Model Overrides for Prompt Steps
+
+A prompt-mode workflow step can specify its own model with:
+
+- `modelProvider`
+- `modelId`
+
+If both are set, step execution uses that model; otherwise it falls back to default model selection.
+
+## Default-On Behavior for New Tasks
+
+Workflow step definitions support `defaultOn`.
+
+When `defaultOn: true`, the step is preselected automatically for newly created tasks (users can still deselect it).
+
+## Viewing Results
+
+Task detail modal includes a **Workflow** tab when workflow data exists.
+
+You can inspect:
+
+- pass/fail/skipped status
+- outputs/findings
+- timing metadata
+
+## Workflow Step APIs
+
+| Endpoint | Purpose |
+|---|---|
+| `GET /api/workflow-steps` | List workflow steps |
+| `POST /api/workflow-steps` | Create workflow step |
+| `PATCH /api/workflow-steps/:id` | Update step |
+| `DELETE /api/workflow-steps/:id` | Delete step |
+| `POST /api/workflow-steps/:id/refine` | AI-refine prompt |
+| `GET /api/workflow-step-templates` | List built-in templates |
+| `POST /api/workflow-step-templates/:id/create` | Materialize template as workflow step |
+
+## Screenshot
+
+![Workflow step manager](./screenshots/workflow-steps.png)
+
+See also: [Task Management](./task-management.md) and [Settings Reference](./settings-reference.md).