Forge IDE — User Flows & E2E Audit Map

Purpose: This page is the canonical map of every user-facing flow in Forge IDE. It serves three goals:

1. Documentation — every path a user can take, with steps, branches, and expected outcomes.
2. E2E test spec — each flow block is written as a repeatable test case an agent or human can execute.
3. Audit baseline — an AI agent can use this page to walk every flow on production (forge-cloud.cmmd.ai) and report pass/fail status.

Last updated: 2026-05-14 | Coverage audit: see Coverage Status section.

How to Use This Page for Agent Auditing

To run an audit, instruct the agent:

“Walk every flow in the Forge IDE User Flows & E2E Audit Map on forge-cloud.cmmd.ai. For each flow, follow the steps exactly, check the expected outcome, and report PASS / FAIL / BLOCKED with one-line notes.”

Each flow block contains: Entry (where/how to start), Pre-conditions (state required), Steps (numbered actions), Expected outcome, Edge cases (errors and branches).

Route Reference

URL Pattern	View	Notes
/	Pulse Dashboard	Home; shows live agent count + recent activity
/login	Login	Auth gate; auto-redirects when unauthenticated
/onboarding	Cloud vs. Local choice	Desktop (Electron) only
/pair	Code pairing	Session pairing flow
/new	New thread landing	Composer with project/model/mode chips
/cmmd-center	CMMD Center	Task hub for the connected CMMD workspace
/$envId/$threadId	Active chat thread	Primary working surface
/draft/$draftId	Draft thread	Local unsaved thread
/project/$envId/$projectId	Project workspace	Project home + link-to-CMMD sheet
/settings	Settings shell	—
/settings/general	General settings	—
/settings/providers	Model provider config	—
/settings/connections	API connections	Desktop only
/settings/cmmd-sync	CMMD sync preferences	—
/settings/browser	Browser automation	—
/settings/archived	Archived threads	—
/settings/agent-workflow	Agent orchestration	—
/settings/agent-context	Agent context config	—

Flow Categories

1. Onboarding & Authentication
2. Project Management
3. Thread Lifecycle
4. Agent Interaction
5. Browser Preview
6. Diff & Code Review
7. Git Operations (via NLP)
8. CMMD Integration
9. Settings Configuration
10. Terminal

1. Onboarding & Authentication

Flow 1.1 — Desktop Onboarding: Cloud vs. Local

Field	Value
Entry	Launch Electron app for the first time
Pre-conditions	Fresh install; no ~/.forge config
E2E status	Not covered

Steps: App opens to /onboarding. Two options: Use Forge Cloud | Run Locally.

Cloud branch: Connecting → OAuth → reload → land on /. Local branch: Direct to /.

Edge cases: OAuth denied/timeout/network failure — toast + fallback.

Flow 1.2 — CMMD Login (Web / Expired Session)

Field	Value
Entry	Navigate to any protected route while unauthenticated
E2E status	Partial (PairingRouteSurface component test only)

Steps: Redirect to /login. Click “Sign in with CMMD”. Poll token endpoint. On success → /.

Edge cases: authorization_pending, slow_down, access_denied, expired_token, session expires mid-session.

2. Project Management

Flow 2.1 — Create Blank Project

Command Palette → “Add project” → Blank Project. Project appears in sidebar; opens /project/$envId/$projectId.

Flow 2.2 — Import CMMD Project

Command Palette → “Add project” → CMMD Project → select from list. Sidebar shows new project with CMMD sync badge.

Known Bug (2026-05-14): Re-importing an already-imported project collapses sidebar layout. Reload recovers.

Flow 2.3 — Clone GitHub Repository

Command Palette → “Add project” → GitHub repository → enter owner/repo or URL. Project added to sidebar.

Flow 2.4 — Clone from Git URL

Command Palette → “Add project” → Git URL → paste full remote URL. Project cloned.

3. Thread Lifecycle

Flow 3.1 — Start New Scratch Thread

Sidebar “New thread” button or /new. Configure: Project / Worktree / Branch / Provider / Model / Interaction mode. Type prompt → Send.

Flow 3.2 — Start CMMD-Task-Anchored Thread

CMMD Center → select task → “Start thread”. Thread carries task anchor; context strip at bottom of thread.

Flow 3.3 — Resume Thread from Pulse Dashboard

/ → “Recent continuations” → click thread card.

4. Agent Interaction

Flow 4.1 — Submit Message and Receive Response

Type message in composer → Enter. Message → user turn → agent response streams. Tool use blocks (file reads, shell commands) appear inline.

Flow 4.2 — Approve Agent Tool Use

ComposerPendingApprovalPanel appears. Counter “1/N” if multiple. Approve or Reject.

Flow 4.3 — Answer Agent Multi-Question Input

ComposerPendingUserInputCard. Single-select auto-advances 200ms. Multi-select uses Next button. Keyboard 1–9 selects.

Flow 4.4 — Plan Mode: Propose, Review, Approve

Toggle “Plan” in composer footer. PlanSidebar opens. Approve & Implement → step-by-step execution; status updates live (⭕ → 🔵 → ✅).

5. Browser Preview

Flow 5.1 — Open Browser Session and Navigate to URL

Click “Browser” tab → state: no-session → click URL bar → enter URL → states: connecting → capture-pending → running (screenshot in canvas).

Edge cases: runtime-unavailable, failed (page load error), idle (no page).

Flow 5.2 — Screenshot Annotation

“Annotate” button → draw box/arrow → comment → “Send annotation”. Composes browser comment prompt with screenshot.

6. Diff & Code Review

Flow 6.1 — Review File Changes in Diff Panel

DiffPanel auto-opens. Files grouped by status: added (green) / modified (yellow) / deleted (red). Per file: unified diff with context. Navigate via scroll + chevron buttons. Approve hunks → agent continues.

7. Git Operations (via NLP)

Git flows have no dedicated slash commands. All are driven by natural language to the agent.

Flow 7.1 — Commit Code

“commit these changes with message ‘[message]’” → agent stages + git commit → hash in response.

Flow 7.2 — Push Branch and Create Pull Request

“push this branch and create a PR” → git push -u origin <branch> + gh pr create → PR URL in thread.

8. CMMD Integration

Flow 8.1 — View and Edit CMMD Task Details

Task panel: Title, Description, Status, Priority, Assignee, Due date, Labels. Inline editor on click. Tabs: Details | Threads | Comments | Attachments.

Flow 8.2 — Post Comment on CMMD Task

TaskDetailPanel → “Comments” tab → textarea → Post.

Flow 8.3 — Link Existing Project to CMMD

/project/$envId/$projectId → “Link to CMMD” button → LinkToCmmdSheet → select CMMD project.

UX gap: post-import linking path is unclear in current build.

9. Settings Configuration

Flow 9.1 — Configure Model Provider

Settings → Providers. Per provider: model selector, binary path or API key, enable/disable.

Flow 9.2 — Configure CMMD Sync Preferences

Settings → CMMD Sync. Auto-create tasks + Push local project dropdowns: Ask each time / Always / Never.

10. Terminal

Flow 10.1 — View Agent Terminal Output

ThreadTerminalDrawer auto-opens. xterm renders previous session history + live stdout/stderr. Scroll, select text, Cmd+Click paths → external IDE, resize drawer.

Coverage Status

Category	Flows	Unit/Component	True E2E
Onboarding & Auth	2	Partial	None
Project Management	4	None	None
Thread Lifecycle	3	None	None
Agent Interaction	4	None	None
Browser Preview	2	None	None
Diff & Code Review	1	None	None
Git Operations	2	None	None
CMMD Integration	3	Partial	None
Settings	2	Partial	None
Terminal	1	Partial	None
Total	24	4 partial	0

Top Priority Gaps

1. Auth flow — login, session expiry, re-auth
2. Project import — CMMD project, GitHub clone
3. Thread start → agent response (full round-trip)
4. Approval gate — command/file-change approval path
5. Browser preview — URL entry through screenshot
6. Diff review + accept
7. Git commit + PR (NLP round-trip)

Known Bugs (2026-05-14)

#	Severity	Flow	Description
1	Blocker	2.2 Import CMMD Project	Re-import collapses sidebar. Reload recovers.
2	Warning	2.3 Clone GitHub	”16 requests slow” toast persists 5+ min
3	Warning	3.1 New Thread	~10s WS disconnect after clone
4	UX	5.1 Browser Preview	URL bar not visually discoverable
5	Info	8.3 Link to CMMD	No post-import linking UI

Related

• Forge Product Roadmap
• Alpha S1 Sprint Retro
• Provider Egress Proxy