The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
Simplify first setup and the path to an agent
deed115611b8fc9
diff --git a/desktop/lib/screens/login_screen.dart b/desktop/lib/screens/login_screen.dartindex e489e6ed4..214374b1d 100644--- a/desktop/lib/screens/login_screen.dart+++ b/desktop/lib/screens/login_screen.dart@@ -3,15 +3,13 @@ import 'package:flutter/material.dart';import '../shared/theme/app_theme.dart' as grid;import '../state/app_state.dart';import '../widgets/login_relay_diagram.dart';+import '../widgets/welcome_workspace_preview.dart';/// The sign-in screen.///-/// This is the first thing a new install shows, and it is the only moment the-/// user is asking themselves *what am I handing this thing?* — so it answers-/// that, with the app's actual architecture, before asking for anything. The-/// diagram is [LoginRelayDiagram]: your machines at one end, the window at the-/// other, and a middle drawn wearing a blindfold because it genuinely cannot-/// read what crosses it.+/// Lead with the work: real coding agents together in one workspace. A static+/// example explains a swarm before sign-in; the privacy guarantee stays in the+/// quiet footer. The preview never creates agents or sends them a task.////// **All four states live here**, in one card, rather than the two screens this/// used to be. Pressing Sign in swapped the whole window for@@ -60,7 +58,7 @@ class LoginScreen extends StatelessWidget {const Positioned.fill(child: LoginAurora()),Center(child: SingleChildScrollView(- padding: const EdgeInsets.symmetric(vertical: 32, horizontal: 24),+ padding: const EdgeInsets.all(24),child: ConstrainedBox(constraints: const BoxConstraints(maxWidth: _cardWidth),child: Container(@@ -70,13 +68,11 @@ class LoginScreen extends StatelessWidget {borderRadius: BorderRadius.circular(14),boxShadow: grid.AppCard.shadow,),- padding: const EdgeInsets.all(32),+ padding: const EdgeInsets.all(24),child: Column(mainAxisSize: MainAxisSize.min,children: [const _AppMark(),- const SizedBox(height: 16),- const LoginRelayDiagram(),const SizedBox(height: 24),Text('All your agents, on one screen',@@ -85,12 +81,14 @@ class LoginScreen extends StatelessWidget {),const SizedBox(height: 8),Text(- 'Your agents keep running on your own machines. '- 'Harness gives you one window onto all of them.',+ 'Work with Claude Code, Codex and other agents side by side. '+ 'Keep related agents together in a swarm.',textAlign: TextAlign.center,style: Theme.of(context).textTheme.bodySmall,),const SizedBox(height: 24),+ const WelcomeWorkspacePreview(),+ const SizedBox(height: 24),_Action(notifier: notifier, waiting: waiting),if (notifier.lastError != null) ...[const SizedBox(height: 16),@@ -139,7 +137,7 @@ class _Action extends StatelessWidget {),const SizedBox(height: 12),Text(- 'Your browser opens for SSO, then this window continues.',+ 'Sign in through your browser. We’ll bring you back here.',textAlign: TextAlign.center,style: Theme.of(context).textTheme.bodySmall,),diff --git a/desktop/lib/screens/swarm_screen.dart b/desktop/lib/screens/swarm_screen.dartindex 434ac5ccc..ae5b6dad1 100644--- a/desktop/lib/screens/swarm_screen.dart+++ b/desktop/lib/screens/swarm_screen.dart@@ -913,6 +913,25 @@ class _SwarmScreenState extends State<SwarmScreen> {notifier: app,projects: _projects.projects,onNewAgent: _newAgent,+ onAgent: (entry) => _activateSearch(+ SwarmSearchSelection(+ SwarmDestination(+ id: agentDestinationId(+ entry.machineId,+ entry.agent.id,+ ),+ title: entry.agent.name,+ detail:+ entry.machine.machine.displayName,+ swarmId: null,+ current: false,+ machineId: entry.machineId,+ agentId: entry.agent.id,+ engine: entry.agent.engine,+ ),+ ),+ app.activeSwarmId,+ ),searchField: SwarmInlineSearch(key: ValueKey('welcome-search:${app.activeSwarmId}',@@ -983,6 +1002,12 @@ class _SwarmScreenState extends State<SwarmScreen> {Expanded(child: TextButton(onPressed: () => app.selectSwarm(swarm.id),+ style: TextButton.styleFrom(+ animationDuration: Duration.zero,+ foregroundColor: app.activeSwarmId == swarm.id+ ? Colors.white+ : Colors.white70,+ ),child: Text(swarm.name,maxLines: 1,diff --git a/desktop/lib/widgets/environment_setup_screen.dart b/desktop/lib/widgets/environment_setup_screen.dartindex cfad26e1a..56124004f 100644--- a/desktop/lib/widgets/environment_setup_screen.dart+++ b/desktop/lib/widgets/environment_setup_screen.dart@@ -8,8 +8,8 @@ import '../shared/widgets/command_row.dart';import '../state/app_state.dart';import '../theme/app_theme.dart';-/// Transparent three-step setup. Launch probes are read-only; changes require-/// an explicit method choice and confirmation on this screen.+/// One setup review with a direct install action. Launch probes stay read-only;+/// installation starts only after the user chooses the visible install action.class EnvironmentSetupScreen extends StatefulWidget {final AppNotifier notifier;@@ -31,39 +31,27 @@ class _EnvironmentSetupScreenState extends State<EnvironmentSetupScreen> {});}- int _stage(EnvironmentSetupPhase phase) => switch (phase) {- EnvironmentSetupPhase.preflight => 0,- EnvironmentSetupPhase.review => 1,- _ => 2,- };-@overrideWidget build(BuildContext context) {final state = widget.notifier.environmentReadiness;return Scaffold(backgroundColor: AppColors.background,- body: LayoutBuilder(- builder: (context, constraints) => Row(- children: [- if (constraints.maxWidth >= 820)- SizedBox(width: 260, child: _Rail(stage: _stage(state.phase))),- Expanded(- child: Column(- children: [- Expanded(- child: SingleChildScrollView(- padding: const EdgeInsets.fromLTRB(44, 38, 44, 28),- child: ConstrainedBox(- constraints: const BoxConstraints(maxWidth: 780),- child: _body(state),- ),- ),- ),- _footer(state),- ],- ),+ body: Center(+ child: SingleChildScrollView(+ padding: const EdgeInsets.all(24),+ child: ConstrainedBox(+ constraints: const BoxConstraints(maxWidth: 760),+ child: Column(+ mainAxisSize: MainAxisSize.min,+ children: [+ Padding(+ padding: const EdgeInsets.fromLTRB(32, 28, 32, 24),+ child: _body(state),+ ),+ _footer(state),+ ],),- ],+ ),),),);@@ -71,7 +59,7 @@ class _EnvironmentSetupScreenState extends State<EnvironmentSetupScreen> {Widget _body(EnvironmentReadiness state) => switch (state.phase) {EnvironmentSetupPhase.preflight => _preflight(state),- EnvironmentSetupPhase.review => _review(state),+ EnvironmentSetupPhase.review ||EnvironmentSetupPhase.chooseMethod => _choose(state),EnvironmentSetupPhase.installing ||EnvironmentSetupPhase.waitingForTerminal ||@@ -107,7 +95,7 @@ class _EnvironmentSetupScreenState extends State<EnvironmentSetupScreen> {crossAxisAlignment: CrossAxisAlignment.start,children: [_heading(- 'Step 1 of 3 · Pre-flight check',+ 'Getting started','Checking this computer','This check is read-only. Harness verifies every tool it needs before proposing any changes.',),@@ -121,18 +109,6 @@ class _EnvironmentSetupScreenState extends State<EnvironmentSetupScreen> {],);- Widget _review(EnvironmentReadiness state) => Column(- crossAxisAlignment: CrossAxisAlignment.start,- children: [- _heading(- 'Step 2 of 3 · Review setup',- 'Here is exactly what is required',- 'Ready items stay untouched. Only missing items continue to setup.',- ),- _checkList(state),- ],- );-Widget _choose(EnvironmentReadiness state) {final mode = state.mode ?? EnvironmentSetupMode.automatic;final items = _installItems(state);@@ -144,30 +120,37 @@ class _EnvironmentSetupScreenState extends State<EnvironmentSetupScreen> {crossAxisAlignment: CrossAxisAlignment.start,children: [_heading(- 'Step 3 of 3 · Choose & install',- 'Choose how to prepare this computer',+ 'Getting started',+ 'Get this computer ready',count == 0? 'Nothing is left to install. Harness will run one final verification.'- : 'Only the $countLabel below will be installed. Ready items stay untouched.',+ : 'Harness brings your coding agents together in one workspace. '+ 'Set up the $countLabel below, then sign in to get started.',),- SegmentedButton<EnvironmentSetupMode>(- segments: const [- ButtonSegment(- value: EnvironmentSetupMode.automatic,- icon: Icon(Icons.auto_fix_high, size: 17),- label: Text('Automatic'),+ Row(+ children: [+ const Expanded(+ child: Text(+ 'Required tools',+ style: TextStyle(fontWeight: FontWeight.w500),+ ),),- ButtonSegment(- value: EnvironmentSetupMode.manual,- icon: Icon(Icons.terminal, size: 17),- label: Text('Manual'),+ TextButton(+ style: TextButton.styleFrom(foregroundColor: AppColors.textSoft),+ onPressed: () => widget.notifier.selectEnvironmentSetupMode(+ mode == EnvironmentSetupMode.automatic+ ? EnvironmentSetupMode.manual+ : EnvironmentSetupMode.automatic,+ ),+ child: Text(+ mode == EnvironmentSetupMode.automatic+ ? 'Manual setup'+ : 'Use automatic setup',+ ),),],- selected: {mode},- onSelectionChanged: (value) =>- widget.notifier.selectEnvironmentSetupMode(value.first),),- const SizedBox(height: 18),+ const SizedBox(height: 8),if (mode == EnvironmentSetupMode.automatic) ...[if (needsTerminal) ...[_notice(@@ -191,9 +174,9 @@ class _EnvironmentSetupScreenState extends State<EnvironmentSetupScreen> {crossAxisAlignment: CrossAxisAlignment.start,children: [_heading(- 'Step 3 of 3 · Installation',+ 'Getting started',state.phase == EnvironmentSetupPhase.waitingForTerminal- ? 'Finish the secure Terminal step'+ ? 'Finish setup in Terminal': state.phase == EnvironmentSetupPhase.verifying? 'Running final verification': 'Preparing this computer',@@ -622,24 +605,15 @@ class _EnvironmentSetupScreenState extends State<EnvironmentSetupScreen> {children: [Expanded(child: Text(- 'No password is collected by Harness.',+ 'Next: sign in and start an agent.',maxLines: 1,overflow: TextOverflow.ellipsis,style: TextStyle(color: AppColors.muted, fontSize: 11),),),const SizedBox(width: 12),- if (state.phase == EnvironmentSetupPhase.review)- FilledButton(- onPressed: widget.notifier.showEnvironmentMethodChoice,- child: const Text('Continue'),- )- else if (state.phase == EnvironmentSetupPhase.chooseMethod) ...[- TextButton(- onPressed: widget.notifier.showEnvironmentReview,- child: const Text('Back'),- ),- const SizedBox(width: 8),+ if (state.phase == EnvironmentSetupPhase.review ||+ state.phase == EnvironmentSetupPhase.chooseMethod) ...[FilledButton.icon(onPressed: busy? null@@ -719,120 +693,6 @@ class _InstallItem {});}-class _Rail extends StatelessWidget {- final int stage;- const _Rail({required this.stage});-- @override- Widget build(BuildContext context) => Container(- padding: const EdgeInsets.fromLTRB(25, 36, 25, 24),- decoration: BoxDecoration(- color: AppColors.sidebar,- border: Border(right: BorderSide(color: AppColors.border)),- ),- child: Column(- crossAxisAlignment: CrossAxisAlignment.start,- children: [- Text(- 'ENVIRONMENT SETUP',- style: TextStyle(- color: AppColors.muted,- fontSize: 10,- fontWeight: FontWeight.w700,- letterSpacing: 1.3,- ),- ),- const SizedBox(height: 8),- const Text(- 'Prepare Harness\nfor this computer',- style: TextStyle(- fontSize: 20,- fontWeight: FontWeight.w600,- height: 1.25,- ),- ),- const SizedBox(height: 30),- for (var index = 0; index < 3; index++)- _RailStep(index: index, stage: stage),- const Spacer(),- Text(- 'Required: tmux · managed Node 20+ · Harness CLI',- style: TextStyle(color: AppColors.muted, fontSize: 11, height: 1.5),- ),- ],- ),- );-}--class _RailStep extends StatelessWidget {- final int index;- final int stage;- const _RailStep({required this.index, required this.stage});-- @override- Widget build(BuildContext context) {- const labels = [- ('Pre-flight check', 'Read-only inspection'),- ('Review setup', 'See every change'),- ('Choose & install', 'Automatic or manual'),- ];- final done = index < stage;- final active = index == stage;- return Container(- margin: const EdgeInsets.only(bottom: 8),- padding: const EdgeInsets.all(10),- decoration: BoxDecoration(- color: active ? AppColors.selected : Colors.transparent,- borderRadius: BorderRadius.circular(9),- ),- child: Row(- children: [- Container(- width: 28,- height: 28,- alignment: Alignment.center,- decoration: BoxDecoration(- shape: BoxShape.circle,- color: active ? AppColors.accent : AppColors.surface,- border: Border.all(color: AppColors.borderStrong),- ),- child: done- ? Icon(Icons.check, size: 14, color: AppColors.success)- : Text(- '${index + 1}',- style: TextStyle(- fontSize: 11,- color: active ? Colors.white : AppColors.textSoft,- ),- ),- ),- const SizedBox(width: 10),- Expanded(- child: Column(- crossAxisAlignment: CrossAxisAlignment.start,- children: [- Text(- labels[index].$1,- style: TextStyle(- fontSize: 12,- fontWeight: FontWeight.w600,- color: active ? AppColors.text : AppColors.textSoft,- ),- ),- const SizedBox(height: 3),- Text(- labels[index].$2,- style: TextStyle(fontSize: 10, color: AppColors.muted),- ),- ],- ),- ),- ],- ),- );- }-}-class _Panel extends StatelessWidget {final Widget child;final EdgeInsetsGeometry padding;diff --git a/desktop/lib/widgets/new_agent_dialog.dart b/desktop/lib/widgets/new_agent_dialog.dartindex 87aa1deca..726832d83 100644--- a/desktop/lib/widgets/new_agent_dialog.dart+++ b/desktop/lib/widgets/new_agent_dialog.dart@@ -76,6 +76,7 @@ class _NewAgentDialog extends StatefulWidget {class _NewAgentDialogState extends State<_NewAgentDialog> {late String _engine = allEngines.first.id;+ bool _engineChosenByUser = false;late String _machineId = widget.machineId;int _machineRevision = 0;late String? _folder = widget.initialFolder;@@ -92,6 +93,7 @@ class _NewAgentDialogState extends State<_NewAgentDialog> {@overridevoid initState() {super.initState();+ _engine = _preferredInstalledEngine();// Which engines this machine actually has. Asked here rather than at// connect because the answer costs the far side one interactive shell per// engine and is only ever read on this screen. Deferred a frame so the@@ -106,11 +108,42 @@ class _NewAgentDialogState extends State<_NewAgentDialog> {// answer lands, so nothing blanks.WidgetsBinding.instance.addPostFrameCallback((_) {if (mounted) {- unawaited(widget.notifier.probeEngines(_machineId, force: true));+ unawaited(_probeEngines());}});}+ String _preferredInstalledEngine() {+ final engines = widget.notifier.stateOf(_machineId)?.engines;+ if (engines?.loaded != true || engines?[_engine]?.installed == true) {+ return _engine;+ }+ return allEngines+ .where((identity) => engines?[identity.id]?.installed == true)+ .firstOrNull+ ?.id ??+ _engine;+ }++ Future<void> _probeEngines() async {+ final machineId = _machineId;+ final revision = _machineRevision;+ await widget.notifier.probeEngines(machineId, force: true);+ if (!mounted ||+ revision != _machineRevision ||+ _submitting ||+ _engineChosenByUser) {+ return;+ }+ final preferred = _preferredInstalledEngine();+ if (preferred == _engine) return;+ setState(() {+ _engine = preferred;+ _codexProfile = null;+ _codexProfilesBusy = true;+ });+ }+/// What this machine said about the selected engine, or null while the probe/// is still out (or when the machine could not answer).///@@ -401,7 +434,7 @@ class _NewAgentDialogState extends State<_NewAgentDialog> {SelectOption(value: machine.machine.machineId,label: machine.isLocalMachine- ? 'Local'+ ? 'This computer': machine.machine.displayName,note: machine.nodeOnline == false? 'Offline'@@ -419,11 +452,22 @@ class _NewAgentDialogState extends State<_NewAgentDialog> {_codexProfilesBusy = true;_error = null;});- unawaited(widget.notifier.probeEngines(id, force: true));+ unawaited(_probeEngines());},),const SizedBox(height: _gapField),- const FieldLabel('Engine'),+ const FieldLabel('Project folder'),+ _FolderControl(+ folder: _folder,+ machineName: _machineName,+ machineIsThisComputer: _machineIsThisComputer,+ picking: _picking,+ hovered: _folderHovered,+ onHover: (value) => setState(() => _folderHovered = value),+ onPressed: _browse,+ ),+ const SizedBox(height: _gapField),+ const FieldLabel('Coding agent'),// The app's own picker, not `DropdownButtonFormField`.//// Material's dropdown renders its own popup, anchors it OVER the field@@ -452,6 +496,7 @@ class _NewAgentDialogState extends State<_NewAgentDialog> {),],onChanged: (value) => setState(() {+ _engineChosenByUser = true;_engine = value;_codexProfile = null;_codexProfilesBusy = true;@@ -500,17 +545,6 @@ class _NewAgentDialogState extends State<_NewAgentDialog> {),),],- const SizedBox(height: _gapField),- const FieldLabel('Working folder'),- _FolderControl(- folder: _folder,- machineName: _machineName,- machineIsThisComputer: _machineIsThisComputer,- picking: _picking,- hovered: _folderHovered,- onHover: (value) => setState(() => _folderHovered = value),- onPressed: _browse,- ),// THE FOLD. What is behind it is what most people never touch: a Codex// home to run under, and the flag that turns the approvals off. Leaving// them in the main column made this a four-question dialog to do adiff --git a/desktop/lib/widgets/swarm_welcome.dart b/desktop/lib/widgets/swarm_welcome.dartindex b6c58551a..b05e18114 100644--- a/desktop/lib/widgets/swarm_welcome.dart+++ b/desktop/lib/widgets/swarm_welcome.dart@@ -7,6 +7,7 @@ import '../shared/theme/app_theme.dart' as grid;import '../shared/widgets/skeleton.dart';import '../state/app_state.dart';import '../state/swarm_catalog.dart';+import 'engine_identity.dart';class SwarmWelcome extends StatelessWidget {const SwarmWelcome({@@ -19,6 +20,7 @@ class SwarmWelcome extends StatelessWidget {required this.onLinkMachine,required this.onMachine,required this.onProject,+ this.onAgent,this.onProjectAgents,});final AppNotifier notifier;@@ -29,12 +31,45 @@ class SwarmWelcome extends StatelessWidget {final VoidCallback onLinkMachine;final ValueChanged<MachineState> onMachine;final ValueChanged<SwarmProjectGroup> onProject;+ final ValueChanged<SwarmAgentRef>? onAgent;final ValueChanged<SwarmProjectGroup>? onProjectAgents;@overrideWidget build(BuildContext context) {grid.AppTheme.watch(context);final app = notifier;final groups = swarmProjects(app, projects);+ final firstWorkspace =+ app.swarms.every((swarm) => swarm.panes.isEmpty) &&+ app.closedHistory.isEmpty;+ final agents = firstWorkspace ? swarmAgents(app) : const <SwarmAgentRef>[];+ final noAgents =+ firstWorkspace &&+ !app.machinesLoading &&+ agents.isEmpty &&+ groups.isEmpty &&+ app.machineStates.length == 1 &&+ app.machineStates.values.first.isLocalMachine &&+ app.machineStates.values.first.agentLoadStatus ==+ AgentLoadStatus.loaded &&+ app.machineStates.values.first.nodeOnline != false &&+ !app.machineStates.values.first.needsLink;+ final readyAgents =+ agents+ .where(+ (entry) =>+ !entry.machine.needsLink &&+ entry.machine.nodeOnline != false &&+ entry.agent.terminalAvailable,+ )+ .toList()+ ..sort((a, b) {+ if (a.machine.isLocalMachine != b.machine.isLocalMachine) {+ return a.machine.isLocalMachine ? -1 : 1;+ }+ return a.agent.name.toLowerCase().compareTo(+ b.agent.name.toLowerCase(),+ );+ });return Stack(fit: StackFit.expand,children: [@@ -50,9 +85,9 @@ class SwarmWelcome extends StatelessWidget {mainAxisSize: MainAxisSize.min,crossAxisAlignment: CrossAxisAlignment.start,children: [- const Text(- 'Start a swarm',- style: TextStyle(+ Text(+ noAgents ? 'Start with one agent' : 'Start a swarm',+ style: const TextStyle(fontSize: 32,fontWeight: FontWeight.w500,letterSpacing: -0.7,@@ -63,9 +98,11 @@ class SwarmWelcome extends StatelessWidget {),),const SizedBox(height: 10),- const Text(- 'Choose a machine or project, or add agents individually.',- style: TextStyle(+ Text(+ noAgents+ ? 'Choose a project folder and an agent. Add more whenever you want to work side by side.'+ : 'A swarm keeps related agents together. Open a machine or project to bring its agents into this tab.',+ style: const TextStyle(fontSize: 13,color: Color(0xffe0dce3),),@@ -88,89 +125,150 @@ class SwarmWelcome extends StatelessWidget {],),const SizedBox(height: 34),- _Glass(- child: LayoutBuilder(- builder: (context, size) {- final machines = _section(- 'Machines',- 'Link machine',- onLinkMachine,- [- if (app.machinesLoading &&- app.machineStates.isEmpty)- const SkeletonList(rows: 3),- for (final machine in app.machineStates.values)- _StarterRow(- icon: Icons.computer_outlined,- name: machine.machine.displayName,- note: machine.needsLink- ? 'Link required'- : machine.nodeOnline == false- ? 'Offline'- : machine.isLocalMachine- ? 'Local'- : null,- count: machine.agents.length,- onTap: () => onMachine(machine),+ if (noAgents)+ _Glass(+ child: _FirstAgentGuide(onLinkMachine: onLinkMachine),+ )+ else ...[+ if (onAgent != null && readyAgents.isNotEmpty) ...[+ _Glass(+ child: Column(+ crossAxisAlignment: CrossAxisAlignment.start,+ children: [+ const Text(+ 'Go to an agent',+ style: TextStyle(+ fontSize: 13,+ fontWeight: FontWeight.w600,),- if (!app.machinesLoading &&- app.machineStates.isEmpty)- const Padding(- padding: EdgeInsets.symmetric(vertical: 18),- child: Text(- 'Link a machine to find its agents.',+ ),+ const SizedBox(height: 8),+ for (final entry in readyAgents.take(3))+ ListTile(+ key: ValueKey(+ 'welcome-agent:${entry.machineId}:${entry.agent.id}',),- ),- ],- );- final projects = _section(- 'Projects',- 'Add project',- onAddProject,- [- for (final group in groups)- _StarterRow(- icon: Icons.folder_outlined,- name: group.name,- count: group.agents.length,- onTap: () => onProject(group),- onManage: onProjectAgents == null- ? null- : () => onProjectAgents!(group),- ),- if (groups.isEmpty)- const Padding(- padding: EdgeInsets.symmetric(vertical: 18),- child: Text(- 'Add a working folder to start a project.',- style: TextStyle(- color: Color(0xffc5bece),+ contentPadding: const EdgeInsets.symmetric(+ horizontal: 4,+ ),+ leading: EngineMark(+ engine: entry.agent.engine,+ size: 22,+ ),+ title: Text(+ entry.agent.name,+ maxLines: 1,+ overflow: TextOverflow.ellipsis,+ style: const TextStyle(fontSize: 13),+ ),+ subtitle: Text(+ [+ entry.machine.machine.displayName,+ entry.project?.name,+ ].whereType<String>().join(' · '),+ maxLines: 1,+ overflow: TextOverflow.ellipsis,+ style: const TextStyle(fontSize: 12,+ color: Colors.white70,),),+ onTap: () => onAgent!(entry),),],- );- return size.maxWidth < 570- ? Column(- children: [- machines,- const SizedBox(height: 24),- projects,- ],- )- : Row(- crossAxisAlignment:- CrossAxisAlignment.start,- children: [- Expanded(child: machines),- const SizedBox(width: 36),- Expanded(child: projects),- ],- );- },+ ),+ ),+ const SizedBox(height: 18),+ ],+ _Glass(+ child: LayoutBuilder(+ builder: (context, size) {+ final machines = _section(+ 'Machines',+ 'Link machine',+ onLinkMachine,+ [+ if (app.machinesLoading &&+ app.machineStates.isEmpty)+ const SkeletonList(rows: 3),+ for (final machine+ in app.machineStates.values)+ _StarterRow(+ icon: Icons.computer_outlined,+ name: machine.machine.displayName,+ note: machine.needsLink+ ? 'Link required'+ : machine.nodeOnline == false+ ? 'Offline'+ : machine.isLocalMachine+ ? 'Local'+ : null,+ count: machine.agents.length,+ onTap: () => onMachine(machine),+ ),+ if (!app.machinesLoading &&+ app.machineStates.isEmpty)+ const Padding(+ padding: EdgeInsets.symmetric(+ vertical: 18,+ ),+ child: Text(+ 'Link a machine to find its agents.',+ ),+ ),+ ],+ );+ final projects = _section(+ 'Projects',+ 'Add project',+ onAddProject,+ [+ for (final group in groups)+ _StarterRow(+ icon: Icons.folder_outlined,+ name: group.name,+ count: group.agents.length,+ onTap: () => onProject(group),+ onManage: onProjectAgents == null+ ? null+ : () => onProjectAgents!(group),+ ),+ if (groups.isEmpty)+ const Padding(+ padding: EdgeInsets.symmetric(+ vertical: 18,+ ),+ child: Text(+ 'Add a working folder to start a project.',+ style: TextStyle(+ color: Color(0xffc5bece),+ fontSize: 12,+ ),+ ),+ ),+ ],+ );+ return size.maxWidth < 570+ ? Column(+ children: [+ machines,+ const SizedBox(height: 24),+ projects,+ ],+ )+ : Row(+ crossAxisAlignment:+ CrossAxisAlignment.start,+ children: [+ Expanded(child: machines),+ const SizedBox(width: 36),+ Expanded(child: projects),+ ],+ );+ },+ ),),- ),+ ],],),),@@ -199,6 +297,7 @@ class SwarmWelcome extends StatelessWidget {const Spacer(),TextButton(onPressed: onAction,+ style: TextButton.styleFrom(foregroundColor: Colors.white70),child: Text(action, style: const TextStyle(fontSize: 11)),),],@@ -209,6 +308,86 @@ class SwarmWelcome extends StatelessWidget {);}+class _FirstAgentGuide extends StatelessWidget {+ const _FirstAgentGuide({required this.onLinkMachine});+ final VoidCallback onLinkMachine;++ @override+ Widget build(BuildContext context) => Column(+ crossAxisAlignment: CrossAxisAlignment.start,+ children: [+ const Text(+ 'Your first workspace',+ style: TextStyle(fontSize: 14, fontWeight: FontWeight.w500),+ ),+ const SizedBox(height: 16),+ for (final (number, title, detail) in const [+ ('1', 'Choose a folder', 'Use a project you already work on.'),+ (+ '2',+ 'Pick your agent',+ 'Claude Code, Codex, or another coding agent.',+ ),+ (+ '3',+ 'Start working',+ 'Your agent opens here. Sign in if needed, then give it a task.',+ ),+ ])+ Padding(+ padding: const EdgeInsets.only(bottom: 14),+ child: Row(+ children: [+ Container(+ width: 28,+ height: 28,+ alignment: Alignment.center,+ decoration: const BoxDecoration(+ color: Colors.white10,+ shape: BoxShape.circle,+ ),+ child: Text(+ number,+ style: const TextStyle(fontSize: 12, color: Colors.white70),+ ),+ ),+ const SizedBox(width: 12),+ Expanded(+ child: Column(+ crossAxisAlignment: CrossAxisAlignment.start,+ children: [+ Text(+ title,+ style: const TextStyle(+ fontSize: 13,+ fontWeight: FontWeight.w500,+ ),+ ),+ const SizedBox(height: 2),+ Text(+ detail,+ style: const TextStyle(+ fontSize: 12,+ color: Colors.white70,+ ),+ ),+ ],+ ),+ ),+ ],+ ),+ ),+ TextButton(+ onPressed: onLinkMachine,+ child: const Text(+ 'Link another machine',+ style: TextStyle(color: Colors.white70),+ ),+ ),+ ],+ );+}+class SwarmSearchField extends StatefulWidget {const SwarmSearchField({super.key,diff --git a/desktop/lib/widgets/welcome_workspace_preview.dart b/desktop/lib/widgets/welcome_workspace_preview.dartnew file mode 100644index 000000000..6d960c023--- /dev/null+++ b/desktop/lib/widgets/welcome_workspace_preview.dart@@ -0,0 +1,134 @@+import 'package:flutter/material.dart';++import '../shared/theme/app_theme.dart' as grid;+import 'engine_identity.dart';+import 'swarm_icon.dart';++/// A static example of the workspace. It never creates or contacts an agent.+class WelcomeWorkspacePreview extends StatelessWidget {+ const WelcomeWorkspacePreview({super.key});++ @override+ Widget build(BuildContext context) {+ grid.AppTheme.watch(context);+ final palette = grid.AppTheme.palette.value;+ return Semantics(+ image: true,+ label: 'Example swarm: Claude Code and Codex working side by side.',+ child: ExcludeSemantics(+ child: Container(+ decoration: BoxDecoration(+ color: palette.workspace,+ borderRadius: BorderRadius.circular(10),+ border: Border.all(color: Colors.white12),+ ),+ clipBehavior: Clip.antiAlias,+ child: Column(+ mainAxisSize: MainAxisSize.min,+ children: [+ Container(+ color: palette.tabBar,+ padding: const EdgeInsets.symmetric(+ horizontal: 12,+ vertical: 10,+ ),+ child: const Row(+ children: [+ SwarmIcon(size: 14, color: Colors.white70),+ SizedBox(width: 8),+ Text(+ 'Your project',+ style: TextStyle(fontSize: 12, color: Colors.white),+ ),+ Spacer(),+ Text(+ '2 agents',+ style: TextStyle(fontSize: 11, color: Colors.white70),+ ),+ ],+ ),+ ),+ Padding(+ padding: const EdgeInsets.all(8),+ child: Row(+ children: [+ Expanded(+ child: _AgentExample(+ engine: 'claude',+ title: 'Claude Code',+ task: 'Build the feature',+ color: palette.background,+ ),+ ),+ const SizedBox(width: 8),+ Expanded(+ child: _AgentExample(+ engine: 'codex',+ title: 'Codex',+ task: 'Review the changes',+ color: palette.background,+ ),+ ),+ ],+ ),+ ),+ ],+ ),+ ),+ ),+ );+ }+}++class _AgentExample extends StatelessWidget {+ const _AgentExample({+ required this.engine,+ required this.title,+ required this.task,+ required this.color,+ });+ final String engine, title, task;+ final Color color;++ @override+ Widget build(BuildContext context) => Container(+ padding: const EdgeInsets.all(12),+ decoration: BoxDecoration(+ color: color,+ borderRadius: BorderRadius.circular(6),+ ),+ child: Column(+ crossAxisAlignment: CrossAxisAlignment.start,+ children: [+ Row(+ children: [+ EngineMark(engine: engine, size: 17),+ const SizedBox(width: 7),+ Expanded(+ child: Text(+ title,+ style: const TextStyle(+ fontSize: 12,+ color: Colors.white,+ fontWeight: FontWeight.w500,+ ),+ ),+ ),+ ],+ ),+ const SizedBox(height: 14),+ Text(task, style: const TextStyle(fontSize: 11, color: Colors.white70)),+ const SizedBox(height: 10),+ for (final width in [0.9, 0.65])+ FractionallySizedBox(+ widthFactor: width,+ child: Container(+ height: 3,+ margin: const EdgeInsets.only(bottom: 5),+ color: Colors.white24,+ ),+ ),+ ],+ ),+ );+}diff --git a/desktop/test/boot_flow_widget_test.dart b/desktop/test/boot_flow_widget_test.dartindex 52916036d..0a66d4da7 100644--- a/desktop/test/boot_flow_widget_test.dart+++ b/desktop/test/boot_flow_widget_test.dart@@ -595,23 +595,27 @@ void main() {);await tester.pump();- expect(find.text('Finish the secure Terminal step'), findsOneWidget);+ expect(find.text('Finish setup in Terminal'), findsOneWidget);expect(find.text('Managed Node 20+ & Harness CLI'), findsOneWidget);expect(find.text('Recheck now'), findsOneWidget);expect(find.text('Harness cannot see your password'), findsOneWidget);},);- testWidgets('environment wizard exposes automatic and manual setup paths', (+ testWidgets('setup review exposes the install action and a manual path', (tester,) async {final app = makeNotifier(AppStatus.preparingEnvironment);app.environmentReadiness = EnvironmentReadiness(steps: {+ EnvironmentStep.clipboard: EnvironmentStepStatus.notApplicable,EnvironmentStep.harness: EnvironmentStepStatus.failed,EnvironmentStep.tmux: EnvironmentStepStatus.ready,},phase: EnvironmentSetupPhase.review,+ systemReady: true,+ homebrewReady: true,+ tmuxBinaryReady: true,);await tester.pumpWidget(ProviderScope(@@ -621,24 +625,71 @@ void main() {);await tester.pump();- expect(find.text('Here is exactly what is required'), findsOneWidget);- expect(find.text('HOST DEPENDENCIES'), findsOneWidget);- expect(find.text('HARNESS COMPONENTS'), findsOneWidget);- expect(find.text('Final verification'), findsNothing);+ expect(find.text('Get this computer ready'), findsOneWidget);+ expect(find.text('Install 1 tool'), findsOneWidget);+ expect(find.text('Continue'), findsNothing);+ expect(find.text('tmux'), findsNothing);expect(find.text('Apple developer tools'), findsNothing);- await tester.tap(find.text('Continue'));- await tester.pump();- expect(find.text('Automatic'), findsOneWidget);- expect(find.text('Manual'), findsOneWidget);- expect(find.text('Admin prompts stay in Terminal'), findsOneWidget);- await tester.tap(find.text('Manual'));+ expect(find.text('Use automatic setup'), findsNothing);+ expect(find.text('Manual setup'), findsOneWidget);+ expect(find.text('Admin prompts stay in Terminal'), findsNothing);+ await tester.tap(find.text('Manual setup'));await tester.pump();expect(find.textContaining('/bin/sh -s -- --desktop'), findsOneWidget);expect(find.text('I ran these · Recheck'), findsOneWidget);});+ testWidgets(+ 'one explicit install action reaches sign-in without an extra review',+ (tester) async {+ final provisioner = _ScriptedEnvironmentProvisioner([+ EnvironmentReadiness(+ steps: {+ for (final step in EnvironmentStep.values)+ step: EnvironmentStepStatus.ready,+ },+ phase: EnvironmentSetupPhase.ready,+ systemReady: true,+ ),+ ]);+ final app = AppNotifier(+ config: AppConfig.dev,+ authSession: AuthSession(),+ configStore: null,+ cliLogin: _FakeCliLogin(),+ environmentProvisioner: provisioner,+ )..status = AppStatus.preparingEnvironment;+ app.environmentReadiness = const EnvironmentReadiness(+ steps: {+ EnvironmentStep.clipboard: EnvironmentStepStatus.notApplicable,+ EnvironmentStep.harness: EnvironmentStepStatus.failed,+ EnvironmentStep.tmux: EnvironmentStepStatus.ready,+ },+ phase: EnvironmentSetupPhase.review,+ systemReady: true,+ homebrewReady: true,+ tmuxBinaryReady: true,+ );+ await tester.pumpWidget(+ ProviderScope(+ overrides: [appStateProvider.overrideWithValue(app)],+ child: const DesktopApp(),+ ),+ );+ await tester.pump();+ expect(provisioner.installCalls, isEmpty);+ await tester.tap(find.text('Install 1 tool'));+ await tester.pump();+ expect(provisioner.installCalls, [true]);+ expect(app.status, AppStatus.unauthenticated);+ expect(find.text('Sign in'), findsOneWidget);+ await tester.pumpWidget(const SizedBox());+ app.dispose();+ },+ );+testWidgets('install plan and manual commands show only missing tools', (tester,) async {@@ -669,7 +720,7 @@ void main() {expect(find.text('Install 2 tools'), findsOneWidget);expect(find.text('Admin prompts stay in Terminal'), findsOneWidget);- await tester.tap(find.text('Manual'));+ await tester.tap(find.text('Manual setup'));await tester.pump();expect(find.text('1 · Homebrew'), findsOneWidget);@@ -733,8 +784,9 @@ void main() {);await tester.pump();- expect(find.text('System tools & writable home'), findsOneWidget);- expect(find.text('Missing'), findsOneWidget);+ expect(find.text('Apple developer tools'), findsOneWidget);+ expect(find.text('Install 1 tool'), findsOneWidget);+ expect(find.text('tmux'), findsNothing);});testWidgets('RootShell rebuilds to LoginScreen when status flips after boot', (diff --git a/desktop/test/first_workspace_test.dart b/desktop/test/first_workspace_test.dartnew file mode 100644index 000000000..488885d71--- /dev/null+++ b/desktop/test/first_workspace_test.dart@@ -0,0 +1,190 @@+import 'dart:async';++import 'package:file_selector_platform_interface/file_selector_platform_interface.dart';+import 'package:flutter/material.dart';+import 'package:flutter_test/flutter_test.dart';+import 'package:harness/auth/auth_session.dart';+import 'package:harness/core/config.dart';+import 'package:harness/core/engine_availability.dart';+import 'package:harness/core/models.dart';+import 'package:harness/shared/widgets/app_select_field.dart';+import 'package:harness/state/app_state.dart';+import 'package:harness/terminal/terminal_binary.dart';+import 'package:xterm/xterm.dart';++import 'swarm_screen_test.dart' show mount, terminal;++class _FirstUseApp extends AppNotifier {+ _FirstUseApp()+ : super(+ config: AppConfig.dev,+ authSession: AuthSession(),+ configStore: null,+ ) {+ hasNavigationRail = false;+ const machine = Machine(+ machineId: 'm',+ name: 'My computer',+ authMode: MachineAuthMode.remote,+ );+ machines = [machine];+ machineStates['m'] = MachineState(machine)+ ..localOnly = true+ ..nodeOnline = true+ ..agentLoadStatus = AgentLoadStatus.loaded;+ }++ Completer<void>? probe;+ final launches =+ <({String machine, String engine, String folder, bool bypass})>[];+ final input = <TerminalBinaryFrame>[];++ @override+ Future<void> probeEngines(String machineId, {bool force = false}) async {+ await probe?.future;+ }++ @override+ Future<String?> createAgent(+ String machineId, {+ required String engine,+ required String folder,+ bool bypassPermission = false,+ String? codexHome,+ String? swarmId,+ }) async {+ launches.add((+ machine: machineId,+ engine: engine,+ folder: folder,+ bypass: bypassPermission,+ ));+ adoptSessionForTest(terminal('created', input));+ notifyListeners();+ return null;+ }+}++class _FolderPicker extends FileSelectorPlatform {+ var opened = 0;+ @override+ Future<String?> getDirectoryPath({+ String? initialDirectory,+ String? confirmButtonText,+ }) async {+ opened++;+ return '/work/my-project';+ }+}++void main() {+ testWidgets('fresh workspace reaches an agent with an installed default', (+ tester,+ ) async {+ final app = _FirstUseApp();+ app.machineStates['m']!.engines.replace(const [+ EngineAvailability(engine: 'claude', installed: false, installable: true),+ EngineAvailability(engine: 'codex', installed: true),+ ]);+ final oldPicker = FileSelectorPlatform.instance;+ final picker = _FolderPicker();+ FileSelectorPlatform.instance = picker;+ addTearDown(() => FileSelectorPlatform.instance = oldPicker);+ await mount(tester, app);++ expect(find.text('Start with one agent'), findsOneWidget);+ expect(find.text('Machines'), findsNothing);+ expect(find.text('Projects'), findsNothing);+ expect(app.launches, isEmpty);+ await tester.tap(find.text('New agent'));+ await tester.pump();+ final engine = tester.widget<AppSelectField<String>>(+ find.byKey(const Key('new-agent-engine-field')),+ );+ final machine = tester.widget<AppSelectField<String>>(+ find.byKey(const Key('new-agent-machine-field')),+ );+ expect(engine.value, 'codex');+ expect(machine.value, 'm');+ expect(+ tester.getTopLeft(find.text('Project folder')).dy,+ lessThan(tester.getTopLeft(find.text('Coding agent')).dy),+ );+ expect(picker.opened, 0);+ await tester.tap(find.text('Browse…'));+ await tester.pump();+ expect(app.launches, isEmpty);+ await tester.tap(find.text('Create agent'));+ await tester.pump();++ expect(app.launches, [+ (+ machine: 'm',+ engine: 'codex',+ folder: '/work/my-project',+ bypass: false,+ ),+ ]);+ expect(find.byType(TerminalView), findsOneWidget);+ expect(find.text('Your first workspace'), findsNothing);+ expect(app.input, isEmpty);+ expect(tester.takeException(), isNull);+ await tester.pumpWidget(const SizedBox());+ app.dispose();+ });++ testWidgets('existing agents open directly from an empty workspace', (+ tester,+ ) async {+ final app = _FirstUseApp();+ app.machineStates['m']!.agents = const [+ Agent(+ id: 'existing',+ name: 'My ongoing work',+ engine: 'codex',+ terminalAvailable: true,+ ),+ ];+ await mount(tester, app);+ expect(app.panes, isEmpty);+ await tester.tap(find.byKey(const ValueKey('welcome-agent:m:existing')));+ await tester.pump();+ expect(app.panes.single.agentId, 'existing');+ expect(app.launches, isEmpty);+ expect(find.text('Go to an agent'), findsNothing);+ expect(tester.takeException(), isNull);+ await tester.pumpWidget(const SizedBox());+ app.dispose();+ });++ testWidgets(+ 'a late probe uses an installed agent without overriding a choice',+ (tester) async {+ for (final chooseExplicitly in [false, true]) {+ final app = _FirstUseApp()..probe = Completer<void>();+ await mount(tester, app);+ await tester.tap(find.text('New agent'));+ await tester.pump();+ if (chooseExplicitly) {+ await tester.tap(find.byKey(const Key('new-agent-engine-field')));+ await tester.pump();+ await tester.tap(find.text('Cursor'));+ await tester.pump();+ }+ app.machineStates['m']!.engines.replace(const [+ EngineAvailability(engine: 'claude', installed: false),+ EngineAvailability(engine: 'codex', installed: true),+ ]);+ app.probe!.complete();+ await tester.pump();+ final engine = tester.widget<AppSelectField<String>>(+ find.byKey(const Key('new-agent-engine-field')),+ );+ expect(engine.value, chooseExplicitly ? 'cursor' : 'codex');+ expect(app.launches, isEmpty);+ await tester.pumpWidget(const SizedBox());+ app.dispose();+ }+ },+ );+}diff --git a/desktop/test/login_screen_test.dart b/desktop/test/login_screen_test.dartindex df3541419..9c198f5ab 100644--- a/desktop/test/login_screen_test.dart+++ b/desktop/test/login_screen_test.dart@@ -8,7 +8,7 @@ import 'package:harness/core/config.dart';import 'package:harness/screens/login_screen.dart';import 'package:harness/shared/theme/app_theme.dart' as grid;import 'package:harness/state/app_state.dart';-import 'package:harness/widgets/login_relay_diagram.dart';+import 'package:harness/widgets/welcome_workspace_preview.dart';/// Wraps the screen in the same chrome `main.dart` gives it, at the app's/// minimum window size — 880×560 — because that is where a card gets cramped@@ -75,14 +75,24 @@ void main() {expect(find.text('All your agents, on one screen'), findsOneWidget);expect(find.text('Sign in'), findsOneWidget);- expect(find.byType(LoginRelayDiagram), findsOneWidget);+ expect(find.byType(WelcomeWorkspacePreview), findsOneWidget);// The real mark, from the bundle — `Icons.memory` used to stand here and// appeared nowhere else in the app.- final logo = tester.widget<Image>(find.byType(Image));+ final logo = tester.widget<Image>(+ find.byWidgetPredicate(+ (widget) =>+ widget is Image &&+ widget.image is AssetImage &&+ (widget.image as AssetImage).assetName == 'assets/app_icon.png',+ ),+ );expect((logo.image as AssetImage).assetName, 'assets/app_icon.png');// The promise the screen exists to make, in words with no jargon in them.- expect(find.textContaining('one window onto all of them'), findsOneWidget);- expect(find.textContaining('SSO'), findsOneWidget);+ expect(+ find.textContaining('Keep related agents together in a swarm'),+ findsOneWidget,+ );+ expect(find.textContaining('Sign in through your browser'), findsOneWidget);expect(find.textContaining('End-to-end encrypted'), findsOneWidget);});@@ -94,8 +104,8 @@ void main() {await tester.pumpWidget(_host(app));await tester.pump(const Duration(milliseconds: 100));- // Still the same card — the diagram never leaves, so the frame can't jump.- expect(find.byType(LoginRelayDiagram), findsOneWidget);+ // Still the same card — the workspace example never leaves, so the frame can't jump.+ expect(find.byType(WelcomeWorkspacePreview), findsOneWidget);expect(find.text('Waiting for your browser'), findsOneWidget);expect(find.text('Cancel'), findsOneWidget);// The idle label is gone, so the two states cannot both be on screen.@@ -144,13 +154,12 @@ void main() {) async {final app = _notifier(AppStatus.unauthenticated);await tester.pumpWidget(_host(app, reduceMotion: true));- // The one case that DOES settle: with animations disabled both clocks are- // parked, so there is no endless frame loop to wait on.+ // The background animation is parked with reduced motion; the workspace+ // example is static in both modes.await tester.pumpAndSettle();- // The point of the parked frame: it is mid-story, so a still viewer still- // sees packets on the wires rather than an empty diagram.- expect(find.byType(LoginRelayDiagram), findsOneWidget);+ // The example stays visible without depending on animation.+ expect(find.byType(WelcomeWorkspacePreview), findsOneWidget);expect(find.text('Sign in'), findsOneWidget);});@@ -167,6 +176,11 @@ void main() {expect(tester.takeException(), isNull);expect(find.text('Sign in'), findsOneWidget);+ expect(find.text('Sign in').hitTestable(), findsOneWidget);+ expect(+ tester.getRect(find.widgetWithText(FilledButton, 'Sign in')).bottom,+ lessThan(tester.view.physicalSize.height),+ );});test('the diagram\'s caption clears the body-text contrast floor', () {@@ -220,21 +234,21 @@ void main() {// Just pressed: in flight, no URL yet.expect(app.pendingAuthorizeUrl, isNull);expect(find.text('Waiting for your browser'), findsOneWidget);- expect(find.byType(LoginRelayDiagram), findsOneWidget);+ expect(find.byType(WelcomeWorkspacePreview), findsOneWidget);// The CLI hands one over; nothing about the screen should change.app.pendingAuthorizeUrl = 'https://auth.example/authorize';app.notifyListeners();await tester.pump(const Duration(milliseconds: 100));expect(find.text('Waiting for your browser'), findsOneWidget);- expect(find.byType(LoginRelayDiagram), findsOneWidget);+ expect(find.byType(WelcomeWorkspacePreview), findsOneWidget);// Signed in: the URL goes while the restore is still running. The card has// to hold until the shell is actually ready.app.pendingAuthorizeUrl = null;app.notifyListeners();await tester.pump(const Duration(milliseconds: 100));- expect(find.byType(LoginRelayDiagram), findsOneWidget);+ expect(find.byType(WelcomeWorkspacePreview), findsOneWidget);});test('every frame of the diagram carries a sealed packet', () {diff --git a/docs/harness-v2-appearance-onboarding.md b/docs/harness-v2-appearance-onboarding.mdindex 2c3e10177..2fb36a04f 100644--- a/docs/harness-v2-appearance-onboarding.md+++ b/docs/harness-v2-appearance-onboarding.md@@ -28,8 +28,16 @@ Verification includes persistence/reload, keyboard operation, narrow layout, con| [VS Code getting started](https://code.visualstudio.com/docs/getstarted/overview) and [walkthroughs](https://code.visualstudio.com/docs/editing/getting-started/tips-and-tricks) | A short route to a first project, with optional walkthroughs and contextual learning. | Lead with the first agent. Teach grouping and shortcuts where the user can immediately use them. || [Warp installation and setup](https://docs.warp.dev/getting-started/quickstart/installation-and-setup) | Current setup allows sign-in to be optional and can import an existing configuration. | Reuse an existing environment wherever possible. Evaluate Harness's actual authentication requirements before changing its sign-in boundary. |-Current source audit: an unprepared computer reaches dependency setup before sign-in; an authenticated empty workspace leads with “Start a swarm,” generic search, New agent, machines and projects. This exposes several unfamiliar choices before the first useful session. Browser sign-in is a real requirement of the current CLI-backed authentication flow; it cannot simply be replaced with an embedded sign-in panel.+The initial source audit found that an unprepared computer reached a three-stage dependency wizard before sign-in, while an authenticated empty workspace led with “Start a swarm,” generic search, New agent, machines and projects. This exposed several unfamiliar choices before the first useful session. Browser sign-in remains a real requirement of the current CLI-backed authentication flow.-The next implementation is a contextual first-workspace path: make the value and next action clear, reuse existing agents when available, make creating a first agent direct, and explain a swarm as agents working side by side. Keep returning users' ordinary New swarm screen fast. No mandatory tour, sample tasks submitted to real agents, or claimed conversion guarantee.+Implemented first-use changes:-First-use validation will use isolated state and stubbed machines/agents. Success means reaching an existing agent without an intermediate browsing step, or reaching a ready-to-create agent with the machine preselected and an obvious folder choice. A fresh-install dependency or provider sign-in may still take longer than a few seconds; those waits must be honest and actionable.+- Setup combines review and method choice in one screen. It shows only missing tools and a direct **Install N tools** action. Manual commands remain available through a secondary **Manual setup** action. Read-only startup checks, explicit installation consent, verification, terminal handoff and failure recovery are preserved. The three-stage rail and intermediate Continue action are gone.+- Sign-in leads with the value and a static example of two familiar coding agents in one swarm. The example cannot run or submit a task. Browser progress, cancellation, errors and the privacy footer remain in the same card; the primary action is visible at the minimum window size.+- An empty first workspace offers up to three existing, available agents directly. A ready local computer with no agents gets a simple folder → coding agent → work explanation instead of empty Machines and Projects columns. The full machine list stays visible for multiple machines, linking issues, offline hosts and ongoing discovery. Existing work removes the first-workspace guidance. No persistent tour state is added.+- New agent places **Project folder** before **Coding agent** and names the local target **This computer**. It prefers an installed coding agent when that fact is known; an asynchronous probe may improve the default but cannot replace an explicit user choice or a submitted launch. Existing profile, installation and permission behavior is preserved.+- Both actual search fields remain available and continue showing results at the field being edited. The first-use agent rows use the existing, revalidated navigation action. Returning users retain the regular New swarm screen.++First-use validation uses isolated state and stubbed machines, agent creation, folder selection and provisioning. It checks direct existing-agent navigation, a new agent becoming visible with no automatic task input, an installed default, explicit-choice preservation after a late probe, and one deliberate install action reaching sign-in. The first visual pass also led to keeping the setup action beside its content and preserving machine-linking rows. Rendered fixtures cover sign-in at 880×560, setup and both empty/populated discovery states at 1280×800.++These are implementation and fixture results, not a measured conversion rate. A fresh-install dependency or provider sign-in may take longer than a few seconds. Observe new users' time to first useful agent, uncertainty at the folder/agent choice, and ability to add a second agent before claiming the onboarding succeeds for everyone.diff --git a/docs/harness-v2-progress.md b/docs/harness-v2-progress.mdindex fee0be10e..ac88ebdc5 100644--- a/docs/harness-v2-progress.md+++ b/docs/harness-v2-progress.md@@ -2,12 +2,20 @@Updated 2026-09-13 with coordinated palettes, Models, combined closed-work History and faster unified search. This is a working preview, not a release.-## Active follow-up: appearance and first use+## Active follow-up: first use and keyboard integration++- The onboarding implementation is in the rebuilt preview. Setup now has one visible installation plan and a direct Install action; manual setup remains secondary. It keeps read-only probing, explicit installation consent, terminal handoff, verification and recovery. Sign-in shows the value and a static two-agent swarm example; the action remains visible at 880×560. The fresh local empty workspace explains folder → agent → work. Existing available agents can be opened directly. The full machine list stays available for linking/offline/multiple-machine states and discovery.+- New agent preselects a known installed coding agent, uses This computer for the local target, and puts Project folder before Coding agent. Late engine discovery cannot replace a deliberate user choice or a submitted launch. Both real search fields and returning-user workflows remain in place. No test task is submitted to real agents, and the example is static.+- **65 focused checks and the full 1,122-test Flutter suite passed, with one existing skip.** Analyzer has no errors/warnings and 12 existing vendored infos. The full run initially caught an implicit non-macOS tab-label color animation; that animation was removed and the complete suite rerun successfully. First-use render fixtures were visually inspected, including the minimum sign-in window and fresh setup/workspace states. Release build succeeded. Logs: `/private/tmp/harness-v2-onboarding-{tests,focus-tests,full-tests,analyze,render,build}.log`; images: `/private/tmp/harness-v2-onboarding-{login,setup,empty,existing}.png`.+- Normally quit verified preview PID 56329 before rebuilding and relaunched the resulting app. Re-observe the process/window before later interaction. CUA previously returned `cgWindowNotFound`; current first-use evidence is isolated rendering and behavior checks, not live onboarding through the user's account. No sign-out, new provider install or live-agent input was used for validation.+- Continue the accepted keyboard plan: keep Cmd-H/J/K/L and Cmd-arrows, Cmd-B, Cmd-S and Cmd-R; reconcile the unused draft catalog with those actual defaults before activation. Then finish commands in search, controlled resizing and optional cached preview. Do not apply the old runtime patch blindly across the new palette/search/onboarding changes.++## Previous checkpoint: coordinated palettes- Added six coordinated palettes in Settings → Appearance: Graphite (neutral default), Dusk (the earlier plum), Midnight, Slate, Forest and Ember. Preview cards support mouse, keyboard and accessibility activation. Selection applies immediately, persists in order and loads before the first frame. Existing theme tokens feed Flutter surfaces, native tabs/search and retained terminal defaults. Agent-emitted colors and the existing ANSI ramp remain intact; controllers, buffers, focus, fonts and sessions are retained.- Verification: **1,118 Flutter tests passed, one existing skip; 295 AppKit checks passed** including hidden native window layout and retained search/tab identity through a palette change. Analyzer has no errors/warnings and the same 12 vendored infos. A focused four-test accessibility rerun passed after correcting the test's semantics-handle cleanup. Settings was rendered and visually inspected at `/private/tmp/harness-v2-palette-settings.png`; the Release build succeeded. Logs: `/private/tmp/harness-v2-palette-{full-tests,native,analyze,accessibility-tests,build}.log`.- Normally quit the verified preview PID 43778 and launched the rebuilt preview, **PID 56329** at the last check. CUA cannot currently obtain its window (`cgWindowNotFound`), although the process is running. Do not claim live palette-switch verification. Continue with isolated UI fixtures and re-observe before any later native interaction. No real-agent input was sent.-- [Appearance and onboarding research](harness-v2-appearance-onboarding.md) records primary-source observations and product decisions. Onboarding is next: reduce first-workspace choices, make the product's value clear, offer an existing agent directly or a clear first-agent action, then explain grouping in context. Use isolated state rather than signing out the user's real account.+- [Appearance and onboarding research](harness-v2-appearance-onboarding.md) records primary-source observations, decisions and the first-use changes described above. Use isolated state rather than signing out the user's real account.- User authorizes autonomous decisions and frequent commits/pushes while away for eight hours. Keep the active goal running, preserve simple Command shortcuts and explicitly disabled Models placeholders. After onboarding, continue keymap runtime integration, commands in search, controlled resizing and optional cached preview, with performance and input correctness checks.## Active follow-up: in-place New swarm search and account-based Models