adb-ready 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -9,6 +9,23 @@ breaking changes.
 
 ## [Unreleased]
 
+## [0.5.1] - 2026-09-25
+
+### Added
+
+- Add a first-device guide under Start that walks new users through USB,
+  Android 11+ Wireless debugging, or an existing emulator before handing off
+  to the normal verified devices, pairing, or connection workflow.
+
+### Fixed
+
+- Make interactive selection unmistakable with one directional cursor and a
+  high-contrast active row, while retaining explicit no-color and ASCII
+  fallbacks and removing distracting markers from inactive choices.
+- Group session launch, planning, bounded verification, wireless connection,
+  and pairing under one focused Start workflow instead of scattering entry
+  actions across unrelated top-level categories.
+
 ## [0.5.0] - 2026-09-21
 
 ### Fixed
@@ -406,7 +423,8 @@ breaking changes.
   explainable configuration precedence.
 - Human, plain, JSON, and NDJSON output across Node, Bun, and Deno entrypoints.
 
-[Unreleased]: https://github.com/Adam014/adb-ready/compare/v0.5.0...HEAD
+[Unreleased]: https://github.com/Adam014/adb-ready/compare/v0.5.1...HEAD
+[0.5.1]: https://github.com/Adam014/adb-ready/compare/v0.5.0...v0.5.1
 [0.5.0]: https://github.com/Adam014/adb-ready/compare/v0.4.1...v0.5.0
 [0.4.1]: https://github.com/Adam014/adb-ready/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/Adam014/adb-ready/compare/v0.3.5...v0.4.0

package/README.md

@@ -71,6 +71,8 @@ them or require an ADB Ready account, hosted service, or model API key.
 
 Running `adb-ready` without a command opens the interactive workflow home.
 `adbr` is the shorter alias for the same CLI.
+New to Android device setup? Open **Start → Set up first device** for a guided
+USB, Wireless debugging, or emulator path.
 The home and its focused menus adapt to the detected terminal width and height,
 including narrow split panes and short terminals, without relying on scrolling
 to reveal an action.

package/dist/cli.js

@@ -3304,7 +3304,7 @@ import process15 from "node:process";
 // package.json
 var package_default = {
   name: "adb-ready",
-  version: "0.5.0",
+  version: "0.5.1",
   description: "Agent-ready Android CLI for reliable ADB sessions, app automation, and verified evidence.",
   private: false,
   type: "module",
@@ -41609,7 +41609,7 @@ async function pruneSessions(options) {
   if (!listed.ok)
     return;
   const completed = listed.value.filter(({ status }) => status !== "running").sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
-  const cutoff = Date.now() - maxAgeDays * 24 * 60 * 60 * 1000;
+  const cutoff = (options.clock ?? (() => new Date))().getTime() - maxAgeDays * 24 * 60 * 60 * 1000;
   const groups = new Map;
   for (const manifest of completed) {
     const key = manifest.projectFingerprint ?? "legacy-unscoped";
@@ -43635,7 +43635,8 @@ async function runDev(options, config4 = {}, dependencies = {}, signal) {
         projectRoot: options.cwd
       }, {
         ...options.sessionStore,
-        projectRoot: options.sessionStore.projectRoot ?? options.cwd
+        projectRoot: options.sessionStore.projectRoot ?? options.cwd,
+        ...dependencies.clock === undefined ? {} : { clock: dependencies.clock }
       });
     } catch {
       problems.push({
@@ -51402,10 +51403,14 @@ function symbols(capabilities) {
 function color(code, value, capabilities) {
   return capabilities.color ? `\x1B[${String(code)}m${value}\x1B[0m` : value;
 }
+function selected(value, capabilities) {
+  return capabilities.color ? `\x1B[1;7m${value}\x1B[0m` : value;
+}
 var style = {
   accent: (value, capabilities) => color(36, value, capabilities),
   dim: (value, capabilities) => color(2, value, capabilities),
   failure: (value, capabilities) => color(31, value, capabilities),
+  selected,
   strong: (value, capabilities) => color(1, value, capabilities),
   success: (value, capabilities) => color(32, value, capabilities),
   warning: (value, capabilities) => color(33, value, capabilities)
@@ -51465,7 +51470,7 @@ function initialIndex(options) {
   }
   return options.findIndex((option) => option.disabled !== true);
 }
-function renderMenu(options, selected, previousLineCount, frame) {
+function renderMenu(options, selected2, previousLineCount, frame) {
   const { capabilities, sink } = options;
   const glyphs = symbols(capabilities);
   const availableColumns = Math.max(19, capabilities.columns - 1);
@@ -51481,14 +51486,15 @@ function renderMenu(options, selected, previousLineCount, frame) {
   const lines = [...options.preamble?.(frame) ?? []];
   lines.push(`${style.dim(top, capabilities)} ${style.strong(truncate(sanitizeTerminalText(options.title), Math.max(8, availableColumns - 4)), capabilities)}`);
   options.options.forEach((option, index) => {
-    const isSelected = index === selected;
-    const pointer = isSelected ? style.accent(glyphs.active, capabilities) : style.dim(option.disabled === true ? glyphs.skipped : glyphs.pending, capabilities);
-    const number8 = style.dim(`[${String(index + 1)}]`, capabilities);
+    const isSelected = index === selected2;
+    const pointer = isSelected ? style.accent(capabilities.unicode ? "›" : ">", capabilities) : option.disabled === true ? style.dim(glyphs.skipped, capabilities) : " ";
+    const number8 = `[${String(index + 1)}]`;
     const disabled = option.disabled === true ? "  · unavailable" : "";
     const recommended = option.recommended === true ? "  · recommended" : "";
     const label = truncate(`${sanitizeTerminalText(option.label)}${disabled}${recommended}`, Math.max(8, availableColumns - 10));
-    const styledLabel = option.disabled === true ? style.dim(label, capabilities) : isSelected ? style.strong(label, capabilities) : label;
-    lines.push(`  ${pointer} ${number8}  ${styledLabel}`);
+    const row = `${number8}  ${label}`;
+    const styledRow = option.disabled === true ? style.dim(row, capabilities) : isSelected ? style.selected(row, capabilities) : `${style.dim(number8, capabilities)}  ${label}`;
+    lines.push(`  ${pointer} ${styledRow}`);
     if (isSelected && option.description !== undefined) {
       for (const description of wrap(option.description, Math.max(10, availableColumns - 9))) {
         lines.push(`  ${style.accent(rail, capabilities)}      ${style.dim(description, capabilities)}`);
@@ -51512,8 +51518,8 @@ async function selectOne(options) {
   if (!options.capabilities.interactive || options.input.setRawMode === undefined) {
     return { kind: "unavailable" };
   }
-  let selected = initialIndex(options.options);
-  if (selected === -1) {
+  let selected2 = initialIndex(options.options);
+  if (selected2 === -1) {
     return { kind: "unavailable" };
   }
   return await new Promise((resolve) => {
@@ -51556,7 +51562,7 @@ async function selectOne(options) {
       resolve(result);
     };
     const draw = () => {
-      lineCount = renderMenu(options, selected, lineCount, frame);
+      lineCount = renderMenu(options, selected2, lineCount, frame);
     };
     const onAbort = () => settle3({ kind: "cancelled", reason: "signal" });
     const cancelEscape = () => {
@@ -51571,13 +51577,13 @@ async function selectOne(options) {
         }
         if (bufferedInput.startsWith("\x1B[A")) {
           bufferedInput = bufferedInput.slice(3);
-          selected = nextEnabled(options.options, selected, -1);
+          selected2 = nextEnabled(options.options, selected2, -1);
           draw();
           continue;
         }
         if (bufferedInput.startsWith("\x1B[B")) {
           bufferedInput = bufferedInput.slice(3);
-          selected = nextEnabled(options.options, selected, 1);
+          selected2 = nextEnabled(options.options, selected2, 1);
           draw();
           continue;
         }
@@ -51593,7 +51599,7 @@ async function selectOne(options) {
         bufferedInput = bufferedInput.slice(1);
         if (character === "\r" || character === `
 `) {
-          const selectedOption = options.options[selected];
+          const selectedOption = options.options[selected2];
           if (selectedOption !== undefined && selectedOption.disabled !== true) {
             settle3({ kind: "selected", value: selectedOption.value });
           }
@@ -51602,7 +51608,7 @@ async function selectOne(options) {
         if (character !== undefined && /^[1-9]$/u.test(character)) {
           const index = Number(character) - 1;
           if (options.options[index] !== undefined && options.options[index]?.disabled !== true) {
-            selected = index;
+            selected2 = index;
             draw();
           }
         }
@@ -51788,6 +51794,190 @@ function startDevControls(options) {
   return { dispose, stopRequested };
 }
 
+// src/ui/device-setup.ts
+function wrap2(value, width) {
+  const words = sanitizeTerminalText(value).split(" ");
+  const lines = [];
+  let current = "";
+  for (const word of words) {
+    const candidate = current === "" ? word : `${current} ${word}`;
+    if (candidate.length <= width) {
+      current = candidate;
+      continue;
+    }
+    if (current !== "")
+      lines.push(current);
+    current = word;
+  }
+  if (current !== "")
+    lines.push(current);
+  return lines;
+}
+function guide(title, steps, capabilities) {
+  const width = Math.max(18, capabilities.columns - 8);
+  const rail = capabilities.unicode ? "│" : "|";
+  const lines = [style.accent(`DEVICE SETUP · ${title}`, capabilities), ""];
+  for (const [index, step] of steps.entries()) {
+    const prefix = `${String(index + 1)}. `;
+    const wrapped = wrap2(step, Math.max(12, width - prefix.length));
+    for (const [lineIndex, line] of wrapped.entries()) {
+      const marker = lineIndex === 0 ? prefix : " ".repeat(prefix.length);
+      lines.push(`${style.dim(rail, capabilities)} ${marker}${line}`);
+    }
+  }
+  lines.push("");
+  return lines;
+}
+function intro(title, detail2, capabilities) {
+  return [
+    style.accent(`DEVICE SETUP · ${title}`, capabilities),
+    ...wrap2(detail2, Math.max(18, capabilities.columns - 4)).map((line) => style.dim(line, capabilities)),
+    ""
+  ];
+}
+async function nextStep(options, title, steps, action, label) {
+  const selected2 = await selectOne({
+    title: "READY FOR ADB READY?",
+    options: [
+      {
+        value: action,
+        label,
+        description: "ADB Ready will verify the target before using it.",
+        recommended: true
+      },
+      { value: "back", label: "Choose another method" }
+    ],
+    input: options.input,
+    sink: options.sink,
+    capabilities: options.capabilities,
+    preamble: () => guide(title, steps, options.capabilities),
+    escapeLabel: "back",
+    ...options.signal === undefined ? {} : { signal: options.signal }
+  });
+  if (selected2.kind !== "selected")
+    return selected2;
+  return selected2.value === "back" ? { kind: "back" } : { kind: "action", action: selected2.value };
+}
+async function showDeviceSetup(options) {
+  while (true) {
+    const target = await selectOne({
+      title: "SET UP YOUR FIRST ANDROID TARGET",
+      options: [
+        {
+          value: "physical",
+          label: "Physical Android device",
+          description: "Connect a phone, tablet, foldable, watch, TV, car, or XR target.",
+          recommended: true
+        },
+        {
+          value: "emulator",
+          label: "Android emulator",
+          description: "Use an existing Android Virtual Device on this computer."
+        }
+      ],
+      input: options.input,
+      sink: options.sink,
+      capabilities: options.capabilities,
+      preamble: () => intro("ANDROID", "Choose how this project will reach its development target.", options.capabilities),
+      escapeLabel: "home",
+      ...options.signal === undefined ? {} : { signal: options.signal }
+    });
+    if (target.kind !== "selected")
+      return target;
+    if (target.value === "emulator") {
+      const result = await nextStep(options, "ANDROID EMULATOR", [
+        "Open Android Studio, then open Device Manager.",
+        "Start an existing Android Virtual Device and wait for its home screen.",
+        "Continue here; ADB Ready will list and verify the running emulator."
+      ], "devices", "Verify running emulator");
+      if (result.kind === "back")
+        continue;
+      return result;
+    }
+    while (true) {
+      const method = await selectOne({
+        title: "HOW SHOULD THIS DEVICE CONNECT?",
+        options: [
+          {
+            value: "usb",
+            label: "USB cable",
+            description: "The most direct first connection; Android asks you to trust this computer.",
+            recommended: true
+          },
+          {
+            value: "wireless",
+            label: "Wireless debugging",
+            description: "Pair Android 11 or newer over the same trusted network."
+          }
+        ],
+        input: options.input,
+        sink: options.sink,
+        capabilities: options.capabilities,
+        preamble: () => [style.accent("DEVICE SETUP · PHYSICAL DEVICE", options.capabilities), ""],
+        escapeLabel: "back",
+        ...options.signal === undefined ? {} : { signal: options.signal }
+      });
+      if (method.kind !== "selected") {
+        if (method.kind === "cancelled" && method.reason === "escape")
+          break;
+        return method;
+      }
+      if (method.value === "usb") {
+        const result2 = await nextStep(options, "USB", [
+          "On Android, open Settings > About phone and tap Build number seven times. Manufacturer paths can vary; Settings search can find Build number.",
+          "Open Developer options and enable USB debugging.",
+          "Connect a data-capable USB cable, unlock the device, and approve the RSA trust prompt."
+        ], "devices", "Verify USB device");
+        if (result2.kind === "back")
+          continue;
+        return result2;
+      }
+      const wireless = await selectOne({
+        title: "WIRELESS DEBUGGING",
+        options: [
+          {
+            value: "pair",
+            label: "Pair this computer",
+            description: "Use Android's temporary six-digit pairing code.",
+            recommended: true
+          },
+          {
+            value: "connect",
+            label: "Connect an already paired device",
+            description: "Discover and verify a device this computer already trusts."
+          }
+        ],
+        input: options.input,
+        sink: options.sink,
+        capabilities: options.capabilities,
+        preamble: () => guide("WIRELESS", [
+          "Keep the computer and Android device on the same trusted network.",
+          "On Android 11 or newer, open Developer options > Wireless debugging and turn it on."
+        ], options.capabilities),
+        escapeLabel: "back",
+        ...options.signal === undefined ? {} : { signal: options.signal }
+      });
+      if (wireless.kind !== "selected") {
+        if (wireless.kind === "cancelled" && wireless.reason === "escape")
+          continue;
+        return wireless;
+      }
+      const result = await nextStep(options, wireless.value === "pair" ? "PAIR WIRELESSLY" : "CONNECT WIRELESSLY", wireless.value === "pair" ? [
+        "In Wireless debugging, choose Pair device with pairing code.",
+        "Keep that screen open. Its pairing address and six-digit code are temporary.",
+        "Continue here; the code is read through a hidden prompt and is never placed in shell history."
+      ] : [
+        "Keep Wireless debugging enabled and stay on the same trusted network.",
+        "Return to the main Wireless debugging screen; its connection port normally differs from the pairing port.",
+        "Continue here; ADB Ready will discover and verify the connected target."
+      ], wireless.value, wireless.value === "pair" ? "Start secure pairing" : "Find and connect device");
+      if (result.kind === "back")
+        continue;
+      return result;
+    }
+  }
+}
+
 // src/ui/ascii-scene.ts
 var FACE_SHADES = ".,:;=+*#%@";
 var LINK_PATH = [
@@ -52011,16 +52201,11 @@ async function showHomeScreen(options) {
     clearInteractiveScreen(options.sink, options.capabilities);
   const rootOptions = [
     {
-      value: "dev",
-      label: "Start development",
-      description: "Prepare one target, ports, logs, and your project command.",
+      value: "start",
+      label: "Start",
+      description: "Develop, connect a device, or run a bounded verification.",
       recommended: true
     },
-    {
-      value: "automation",
-      label: "Test & automate",
-      description: "Preview readiness, run bounded checks, and keep evidence."
-    },
     {
       value: "device",
       label: "Device & app",
@@ -52039,7 +52224,28 @@ async function showHomeScreen(options) {
     { value: "exit", label: "Exit", description: "Close ADB Ready." }
   ];
   const sectionOptions = {
-    automation: [
+    start: [
+      {
+        value: "dev",
+        label: "Development session",
+        description: "Prepare one target, ports, logs, and your project command.",
+        recommended: true
+      },
+      {
+        value: "setup-device",
+        label: "Set up first device",
+        description: "Follow a guided USB, Wireless debugging, or emulator setup."
+      },
+      {
+        value: "connect",
+        label: "Connect wirelessly",
+        description: "Discover and verify an already paired Wireless debugging target."
+      },
+      {
+        value: "pair",
+        label: "Pair a new device",
+        description: "Pair safely with Android's temporary six-digit code."
+      },
       {
         value: "dev-plan",
         label: "Preview project plan",
@@ -52049,16 +52255,6 @@ async function showHomeScreen(options) {
         value: "run-help",
         label: "Run a bounded verification",
         description: "See how to gate a test on readiness and retain its evidence."
-      },
-      {
-        value: "sessions",
-        label: "Review recent runs",
-        description: "Find completed, failed, or interrupted project sessions."
-      },
-      {
-        value: "context",
-        label: "Create AI debug context",
-        description: "Compile the latest run into a compact redacted brief."
       }
     ],
     device: [
@@ -52076,16 +52272,6 @@ async function showHomeScreen(options) {
         value: "app-restart",
         label: "Restart project app",
         description: "Verify a clean stop and launch on the selected target."
-      },
-      {
-        value: "connect",
-        label: "Connect wirelessly",
-        description: "Discover and verify an already paired Wireless debugging target."
-      },
-      {
-        value: "pair",
-        label: "Pair a new target",
-        description: "Pair safely with Android's temporary six-digit code."
       }
     ],
     debug: [
@@ -52157,7 +52343,7 @@ async function showHomeScreen(options) {
     const visibleOptions = density === "minimal" ? currentOptions.map(({ description: _description, ...option }) => option) : currentOptions;
     const numericShortcut = `1-${String(Math.min(currentOptions.length, 9))} jump`;
     const selection2 = await selectOne({
-      title: atRoot ? "WHAT DO YOU WANT TO DO?" : `HOME / ${section === "device" ? "DEVICE & APP" : section === "debug" ? "DEBUG & EVIDENCE" : section === "automation" ? "TEST & AUTOMATE" : "PROJECT & SETUP"}`,
+      title: atRoot ? "WHAT DO YOU WANT TO DO?" : `HOME / ${section === "start" ? "START" : section === "device" ? "DEVICE & APP" : section === "debug" ? "DEBUG & EVIDENCE" : "PROJECT & SETUP"}`,
       options: visibleOptions,
       input: options.input,
       sink: options.sink,
@@ -52188,7 +52374,7 @@ async function showHomeScreen(options) {
       }
       return { kind: "cancelled", reason: selection2.reason };
     }
-    if (atRoot && selection2.value !== "dev" && selection2.value !== "exit") {
+    if (atRoot && selection2.value !== "exit") {
       section = selection2.value;
       continue;
     }
@@ -54463,14 +54649,14 @@ function parseArguments(argv) {
     } else if (uiAction === "swipe" || uiAction === "scroll") {
       const direction = uiOperands[0];
       if ((uiOperands.length === 1 || uiAction === "scroll" && uiOperands.length === 2) && direction !== undefined && new Set(["down", "left", "right", "up"]).has(direction)) {
-        const selected = selector(uiOperands[1]);
-        if (uiAction === "scroll" && uiOperands.length === 2 && selected === undefined) {
+        const selected2 = selector(uiOperands[1]);
+        if (uiAction === "scroll" && uiOperands.length === 2 && selected2 === undefined) {
           return failure4("CLI_USAGE", "ui scroll accepts an optional valid selector after direction.");
         }
         uiRequest = uiAction === "scroll" ? {
           action: "scroll",
           direction,
-          ...selected === undefined ? {} : { selector: selected }
+          ...selected2 === undefined ? {} : { selector: selected2 }
         } : { action: "swipe", direction };
       } else if (uiAction === "swipe" && uiOperands.length === 4) {
         const values2 = uiOperands.map(coordinate);
@@ -54489,13 +54675,13 @@ function parseArguments(argv) {
       }
     } else if (uiAction === "type" || uiAction === "fill") {
       if (uiAction === "fill") {
-        const selected = selector(uiOperands[0]);
-        if (uiOperands.length !== 2 || selected === undefined) {
+        const selected2 = selector(uiOperands[0]);
+        if (uiOperands.length !== 2 || selected2 === undefined) {
           return failure4("CLI_USAGE", "ui fill requires one valid selector and one text value.");
         }
         uiRequest = {
           action: "fill",
-          selector: selected,
+          selector: selected2,
           text: uiOperands[1] ?? "",
           ...uiSubmit ? { submit: true } : {}
         };
@@ -54515,13 +54701,13 @@ function parseArguments(argv) {
       }
       uiRequest = { action: "press", key: key2 };
     } else if (uiAction === "find" || uiAction === "get" || uiAction === "assert" || uiAction === "clear") {
-      const selected = selector(uiOperands[0]);
-      if (uiOperands.length !== 1 || selected === undefined) {
+      const selected2 = selector(uiOperands[0]);
+      if (uiOperands.length !== 1 || selected2 === undefined) {
         return failure4("CLI_USAGE", `ui ${uiAction} requires one valid selector.`);
       }
-      uiRequest = uiAction === "find" ? { action: "find", selector: selected } : uiAction === "get" ? { action: "get", selector: selected } : uiAction === "clear" ? { action: "clear", selector: selected } : {
+      uiRequest = uiAction === "find" ? { action: "find", selector: selected2 } : uiAction === "get" ? { action: "get", selector: selected2 } : uiAction === "clear" ? { action: "clear", selector: selected2 } : {
         action: "assert",
-        selector: selected,
+        selector: selected2,
         ...uiWaitState === undefined ? {} : { state: uiWaitState }
       };
     } else if (uiAction === "compare") {
@@ -55260,6 +55446,26 @@ async function runInteractiveSession(io, dependencies, terminal2, signal) {
     if (home.action === "exit") {
       return 0 /* Success */;
     }
+    if (home.action === "setup-device") {
+      clearInteractiveScreen(io.error, terminal2);
+      const setup = await showDeviceSetup({
+        input: io.input,
+        sink: io.error,
+        capabilities: terminal2,
+        ...signal === undefined ? {} : { signal }
+      });
+      if (setup.kind === "cancelled" && setup.reason !== "escape") {
+        return 130 /* Interrupted */;
+      }
+      if (setup.kind === "action") {
+        clearInteractiveScreen(io.error, terminal2);
+        await runCliInternal([setup.action], io, dependencies, signal);
+      }
+      if (signal?.aborted === true)
+        return 130 /* Interrupted */;
+      presentation = "menu";
+      continue;
+    }
     const actionArguments = {
       "app-info": ["app", "info"],
       "app-restart": ["app", "restart"],
@@ -55702,13 +55908,13 @@ async function runCliInternal(argv, io, dependencies = {}, signal) {
       }
     }
     const shouldPrompt = options.select || (options.command === "app" && options.appAction !== "resolve" || options.command === "apps" || options.command === "capture" || options.command === "dev" || options.command === "run" || options.command === "inspect" || options.command === "logs" || options.command === "open" || options.command === "ui") && errorCapabilities.interactive && inventory.result.data?.selected === undefined && selectable.length !== 1;
-    const selected = shouldPrompt ? await selectDevice(inventory, io, errorCapabilities, lastTarget, signal) : inventory;
-    if (!selected.result.ok || selected.result.data?.selected === undefined) {
+    const selected2 = shouldPrompt ? await selectDevice(inventory, io, errorCapabilities, lastTarget, signal) : inventory;
+    if (!selected2.result.ok || selected2.result.data?.selected === undefined) {
       if (shouldPrompt) {
         if (autonomousRun) {
-          return await finishAutonomousFailure([...selected.result.problems], selected.exitCode);
+          return await finishAutonomousFailure([...selected2.result.problems], selected2.exitCode);
         }
-        renderResult({ ...selected.result, command: options.command }, {
+        renderResult({ ...selected2.result, command: options.command }, {
           format: "human",
           capabilities: errorCapabilities,
           sink: io.error,
@@ -55716,10 +55922,10 @@ async function runCliInternal(argv, io, dependencies = {}, signal) {
         });
         await preparedAvd?.release(signal);
         preparedAvd = undefined;
-        return selected.exitCode;
+        return selected2.exitCode;
       }
     } else {
-      preparedSelection = selected.result.data.selected;
+      preparedSelection = selected2.result.data.selected;
       const transport = preparedSelection.transport;
       if (options.avdName !== undefined || transport.transportId === undefined) {
         config4.targetSelector = transport.serial;
@@ -56332,4 +56538,4 @@ try {
   process16.removeListener("SIGTERM", abort);
 }
 
-//# debugId=3E670EE2440F454C64756E2164756E21
+//# debugId=3D497281264093F564756E2164756E21

package/docs/getting-started.md

@@ -28,7 +28,12 @@ npx adb-ready doctor
 ```
 
 Run `npx adb-ready` without a command for the interactive workflow home. Its
-layout automatically switches to a compact form in narrow terminal panes.
+layout automatically switches to a compact form in narrow terminal panes. Open
+**Start** for development sessions, bounded verification, wireless connection,
+pairing, or **Set up first device**. The guided setup walks through a physical
+Android device over USB, Android 11+ Wireless debugging, or an existing Android
+emulator, then hands off to the normal verified target workflow. The remaining
+sections keep device operations, debugging, and project setup separate.
 
 The full source build can be tested from a repository checkout:
 

package/docs/targets-and-wireless.md

@@ -3,6 +3,10 @@
 ADB Ready models USB devices, emulators, TCP transports, and TLS Wireless
 debugging transports behind one deterministic selection contract.
 
+For a first connection, run `adb-ready` and open **Start → Set up first
+device**. The interactive guide explains the Android-side steps, then reuses the
+same verified `devices`, `pair`, or `connect` workflow documented below.
+
 ## Inspect visible targets
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adb-ready",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Agent-ready Android CLI for reliable ADB sessions, app automation, and verified evidence.",
   "private": false,
   "type": "module",

package/schema/agent-tools-v1.json

@@ -1,7 +1,7 @@
 {
   "title": "ADB Ready agent tool contract",
   "schemaVersion": 1,
-  "packageVersion": "0.5.0",
+  "packageVersion": "0.5.1",
   "protocolVersion": "2025-11-25",
   "transport": "stdio",
   "tools": [