fix(device): fit start's next steps to the session state

A queued or provisioning session can't be inspected yet, so start now
suggests dcd device status first and points at --wait. It suggests
install when no app was given, and ends with dcd device --help.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: riglar

src/commands/device.ts

@@ -234,6 +234,28 @@ export function platformOfModel(catalogue: DeviceCatalogue, model: string): 'and
   throw new CliError(`"${model}" is a model on both iOS and Android. Pass --platform ios or --platform android.`);
 }
 
+/**
+ * The "Next steps" `dcd device start` prints. They follow the session: a
+ * device that isn't ready yet can't be inspected, so that comes first, and
+ * a session with no app gets the install step.
+ */
+export function startNextSteps(session: DeviceSession, hasApp: boolean): [string, string][] {
+  const { id } = session;
+  const steps: [string, string][] = [];
+  if (!USABLE_STATES.has(session.state)) {
+    steps.push(['check it is ready', `dcd device status ${id}`]);
+  }
+
+  if (!hasApp) steps.push(['install an app', `dcd device install ${id} <app>`]);
+  steps.push(
+    ['inspect the screen', `dcd device inspect ${id}`],
+    ['run a flow', `dcd device run ${id} flow.yaml`],
+    ['stop', `dcd device stop ${id}`],
+    ['all commands', 'dcd device --help'],
+  );
+  return steps;
+}
+
 const startSub = defineCommand({
   meta: { name: 'start', description: 'Start a device session' },
   args: {
@@ -373,15 +395,12 @@ const startSub = defineCommand({
           logger.log(ui.section('Device session'));
           printSession(session);
           logger.log(ui.section('Next steps'));
-          logger.log(
-            ui.branch(
-              ui.fields([
-                ['inspect the screen', colors.highlight(`dcd device inspect ${session.id}`)],
-                ['run a flow', colors.highlight(`dcd device run ${session.id} flow.yaml`)],
-                ['stop', colors.highlight(`dcd device stop ${session.id}`)],
-              ]),
-            ),
-          );
+          const hasApp = Boolean(installedId ?? uploadedId);
+          const steps = startNextSteps(session, hasApp);
+          logger.log(ui.branch(ui.fields(steps.map(([label, cmd]) => [label, colors.highlight(cmd)]))));
+          if (!USABLE_STATES.has(session.state)) {
+            logger.log(ui.info('Next time, `dcd device start --wait` waits until the device is ready.'));
+          }
         },
       };
     });

test/unit/device-command.test.ts

@@ -11,6 +11,7 @@ import {
   deviceCommand,
   newLogLines,
   parseEnvFlags,
+  startNextSteps,
 } from '../../src/commands/device.js';
 import { DeviceApiError } from '../../src/gateways/device-gateway.js';
 import type { DeviceSession } from '../../src/types/domain/device-session.types.js';
@@ -730,6 +731,25 @@ describe('dcd device', () => {
   });
 
   describe('helpers', () => {
+    it('startNextSteps fits the session: check readiness first, install only with no app', () => {
+      const cmds = (s: DeviceSession, hasApp: boolean) => startNextSteps(s, hasApp).map(([, cmd]) => cmd);
+
+      expect(cmds(session('a', { state: 'queued' }), false)).to.deep.equal([
+        'dcd device status a',
+        'dcd device install a <app>',
+        'dcd device inspect a',
+        'dcd device run a flow.yaml',
+        'dcd device stop a',
+        'dcd device --help',
+      ]);
+      expect(cmds(session('a', { state: 'ready' }), true)).to.deep.equal([
+        'dcd device inspect a',
+        'dcd device run a flow.yaml',
+        'dcd device stop a',
+        'dcd device --help',
+      ]);
+    });
+
     it('formatWhen says how far off a time is', () => {
       const now = Date.parse('2026-10-19T10:00:00Z');
       expect(formatWhen('2026-10-19T10:12:00Z', now)).to.match(/^in 12m \(.+\)$/);