Tell strangers the first-run order and name --ios-version on missing runtimes.

Why:
Public Use it mixed install options with hello world and did not say the
app is the preferred host setup. Hello world acquired a lease without
stopping on unavailable or repair_needed capacity. The app missing-CLI
screen led with SIMBROKER_CLI_PATH. host init --bootstrap-config failed
with runtime-not-found without naming --ios-version.

Changed:
README and getting-started now order Homebrew CLI, cask, then Set Up
This Mac / Complete first-time setup (or host init --bootstrap-config
and service start) before hello world. Capacity check gates lease
acquire. Missing-CLI copy leads with the brew formula and Refresh.
runtime-not-found errors name --ios-version and xcrun simctl list
runtimes. Default starter iOS stays 18.

Verification:
npm run agent:verify -- --profile spec-only --paths README.md,docs/getting-started.md,docs/status.md,docs/test/front-door.test.mjs,CHANGELOG.md,spec/build-and-test.md,app/Sources/SharedViews.swift,app/Sources/BrokerOnboardingCommands.swift,app/Tests/BrokerOnboardingCommandsTests.swift,broker-core/index.mjs,broker-core/test/broker-core.test.mjs,broker-core/test/support/simctl-fixture.mjs,client/test/simbroker.test.mjs,client/command-dispatch.mjs --session-dir task-sessions/first-run-onboarding-20260819
npm run agent:verify -- --profile implementation --paths README.md,docs/getting-started.md,docs/status.md,docs/test/front-door.test.mjs,CHANGELOG.md,spec/build-and-test.md,app/Sources/SharedViews.swift,app/Sources/BrokerOnboardingCommands.swift,app/Tests/BrokerOnboardingCommandsTests.swift,broker-core/index.mjs,broker-core/test/broker-core.test.mjs,broker-core/test/support/simctl-fixture.mjs,client/test/simbroker.test.mjs,client/command-dispatch.mjs --session-dir task-sessions/first-run-onboarding-20260819
node --test docs/test/front-door.test.mjs
npm run test:app:focus -- SimulatorBrokerAppTests/BrokerOnboardingCommandsTests

Affected:
README.md
docs/getting-started.md
docs/status.md
docs/test/front-door.test.mjs
CHANGELOG.md
spec/build-and-test.md
app/Sources/BrokerOnboardingCommands.swift
app/Sources/SharedViews.swift
app/Tests/BrokerOnboardingCommandsTests.swift
broker-core/index.mjs
broker-core/test/broker-core.test.mjs
broker-core/test/support/simctl-fixture.mjs
client/command-dispatch.mjs
client/test/simbroker.test.mjs

Refs:
spec/build-and-test.md
docs/getting-started.md

Session:
task-sessions/first-run-onboarding-20260819

Author: VladimirBrejcha

CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- Public first-run order is Homebrew CLI, Homebrew cask, then **Set Up This
+  Mac** / **Complete first-time setup** (or `host init --bootstrap-config`
+  and `service start`). Hello world runs only after a host config exists
+  and after `capacity check --purpose agent-ui-session`; stop on
+  `unavailable` or `repair_needed` and use `doctor` / `simulators repair`.
+  Homebrew does not create simulators.
+- The app **Finish Local Broker Installation** copy leads with
+  `brew install fiveonecode/simulator-broker/simbroker` and **Refresh**.
+- `host init --bootstrap-config` `runtime-not-found` errors name
+  `--ios-version` and `xcrun simctl list runtimes`. Default starter iOS
+  stays `18`.
+
 ### Added
 
 - Homebrew formula `Formula/simbroker.rb` installs the Alpha CLI tarball

README.md

@@ -27,7 +27,10 @@ If you only ever use one simulator by hand, you may not need this yet.
 
 ## Use it
 
-One-line CLI install on macOS, with Node.js 20+ still required at runtime:
+Install the Homebrew CLI, then the Homebrew cask, then set up this Mac.
+The five-minute hello world is only after a host config exists. Homebrew
+does not create Simulator devices. Node.js 20+ is still required at
+runtime.
 
 ```bash
 brew install fiveonecode/simulator-broker/simbroker
@@ -39,6 +42,28 @@ Homebrew clones
 for that tap name. `Formula/` and `Casks/` in this repository stay the
 source of truth.
 
+```bash
+brew install --cask fiveonecode/simulator-broker/simulator-broker
+```
+
+That cask downloads `Simulator-Broker-<version>.zip` from
+[GitHub Releases](https://github.com/fiveonecode/simulator-broker/releases).
+
+The app is the preferred first-run host setup. Open `Simulator Broker.app`.
+If it shows **Set Up This Mac**, click **Complete first-time setup**. That
+runs the same broker commands as:
+
+```bash
+simbroker host init --bootstrap-config
+simbroker service start
+```
+
+`host init --bootstrap-config` prints a warning and then creates real
+Simulator devices. Do not run it casually on a machine whose simulator
+inventory you cannot afford to change.
+
+Other CLI install options:
+
 ```bash
 npm install -g https://github.com/fiveonecode/simulator-broker/releases/download/v0.1.0-alpha.1/simbroker-0.1.0-alpha.1.tgz
 simbroker --help
@@ -58,27 +83,14 @@ build the macOS app. If Homebrew is installed, `simbroker` lands in
 and one guarded login-shell PATH line. Open a new terminal if this shell still
 cannot resolve `simbroker`. `source .../env.sh` remains a fallback.
 
-The Homebrew cask installs the signed, notarized operator app:
-
-```bash
-brew install --cask fiveonecode/simulator-broker/simulator-broker
-```
-
-That cask downloads `Simulator-Broker-<version>.zip` from
-[GitHub Releases](https://github.com/fiveonecode/simulator-broker/releases).
-
 Xcode is still required to create and run iOS Simulators. Alpha CLI tarballs
 are also attached to those releases. Extract a tarball and run
 `./bin/simbroker --help`.
 
 `simbroker` help and `simbroker doctor` print human-readable text by default.
 Pass `--json` for machine-readable payloads.
 
-First-run host setup is `simbroker host init --bootstrap-config`. It prints a
-warning and then creates real Simulator devices. Do not run it casually on a
-machine whose simulator inventory you cannot afford to change.
-
-To install the operator app as well, use the contributor command in
+To build the operator app from this checkout, use the contributor command in
 [Develop it](#develop-it).
 
 ## Develop it
@@ -100,21 +112,28 @@ keep the `agent:context` / `agent:verify` / `agent:complete` track.
 
 ## Five-minute hello world
 
-After the CLI resolves and this Mac has a host config:
+After the CLI resolves and this Mac has a host config from the first-run step
+above:
 
 ```bash
 mkdir -p /tmp/sample-broker-repo && cd /tmp/sample-broker-repo
 simbroker project init
 simbroker project validate
 simbroker capacity check --purpose agent-ui-session --json
+```
+
+If that check is `unavailable` or `repair_needed`, stop. Run
+`simbroker doctor` and `simbroker simulators repair` instead of acquiring
+a lease.
+
+If the purpose is available:
+
+```bash
 simbroker lease acquire --purpose agent-ui-session --lease-file /tmp/simbroker-hello-lease.json
 simbroker host status
 simbroker lease release --lease-file /tmp/simbroker-hello-lease.json
 ```
 
-`host init --bootstrap-config` provisions real Simulator devices. Do not run it
-casually on a machine whose simulator inventory you cannot afford to change.
-
 ## Next reading
 
 - [Getting started](docs/getting-started.md) — install, first-run, reinstall, and uninstall

app/Sources/BrokerOnboardingCommands.swift

@@ -31,6 +31,16 @@ struct BrokerCLIInvocationFormatter {
   }
 }
 
+enum BrokerMissingCLISetupCopy {
+  static let brewInstallCommand = "brew install fiveonecode/simulator-broker/simbroker"
+  static let refreshActionTitle = "Refresh"
+  static let heroMessage =
+    "Install the Homebrew CLI with `brew install fiveonecode/simulator-broker/simbroker`, then click Refresh. The app cannot finish first-run setup until that CLI is on this Mac."
+  static let manualFallbackText =
+    "The public path is the Homebrew formula, then Refresh. Development builds may still set SIMBROKER_CLI_PATH."
+  static let manualFallbackCommands = [brewInstallCommand]
+}
+
 struct RepoOnboardingCommandGuide {
   let commands: [String]
   let shellHelpText: String

app/Sources/SharedViews.swift

@@ -346,7 +346,7 @@ struct BrokerSetupView: View {
             .disabled(store.isApplyingAction || primaryActionEnabled == false)
           }
 
-          Button("Refresh") {
+          Button(BrokerMissingCLISetupCopy.refreshActionTitle) {
             store.refreshNow()
           }
           .buttonStyle(.bordered)
@@ -422,7 +422,7 @@ struct BrokerSetupView: View {
   private var heroMessage: String {
     switch store.startupState {
     case .missingCLI:
-      return "The app cannot find a usable `simbroker` CLI yet, so it cannot self-serve machine setup. Once the CLI is available, this screen can initialize the Mac and start brokerd for you."
+      return BrokerMissingCLISetupCopy.heroMessage
     case .needsHostBootstrap:
       return "This Mac has not been initialized for Simulator Broker yet. First-run setup will create the starter simulator pool, write host config, and start brokerd."
     case .needsServiceStart:
@@ -475,9 +475,7 @@ struct BrokerSetupView: View {
 
     switch store.startupState {
     case .missingCLI:
-      return [
-        "export SIMBROKER_CLI_PATH=/absolute/path/to/simbroker",
-      ]
+      return BrokerMissingCLISetupCopy.manualFallbackCommands
     case .needsHostBootstrap:
       return [
         formatter.command("host init --bootstrap-config --host-config \"\(store.hostConfigPath)\" --state-root \"\(store.stateRootPath)\""),
@@ -501,7 +499,7 @@ struct BrokerSetupView: View {
   private var manualFallbackText: String {
     switch store.startupState {
     case .missingCLI:
-      return "If you are running a development build, point the app at a repo-local CLI with `SIMBROKER_CLI_PATH` or reinstall the packaged broker so \(store.cliHintPath) exists."
+      return BrokerMissingCLISetupCopy.manualFallbackText
     case .needsHostBootstrap:
       return "CLI fallback for the same first-run setup flow."
     case .needsServiceStart, .readOnlySnapshot:

app/Tests/BrokerOnboardingCommandsTests.swift

@@ -2,6 +2,38 @@ import XCTest
 @testable import SimulatorBrokerApp
 
 final class BrokerOnboardingCommandsTests: XCTestCase {
+  func testMissingCLICopyLeadsWithHomebrewFormulaAndRefresh() {
+    XCTAssertEqual(
+      BrokerMissingCLISetupCopy.brewInstallCommand,
+      "brew install fiveonecode/simulator-broker/simbroker"
+    )
+    XCTAssertEqual(BrokerMissingCLISetupCopy.refreshActionTitle, "Refresh")
+    XCTAssertTrue(
+      BrokerMissingCLISetupCopy.heroMessage.contains(BrokerMissingCLISetupCopy.brewInstallCommand)
+    )
+    XCTAssertTrue(
+      BrokerMissingCLISetupCopy.heroMessage.contains(BrokerMissingCLISetupCopy.refreshActionTitle)
+    )
+    XCTAssertEqual(
+      BrokerMissingCLISetupCopy.manualFallbackCommands,
+      [BrokerMissingCLISetupCopy.brewInstallCommand]
+    )
+    XCTAssertTrue(
+      BrokerMissingCLISetupCopy.manualFallbackText.hasPrefix("The public path is the Homebrew formula, then Refresh.")
+    )
+    XCTAssertFalse(
+      BrokerMissingCLISetupCopy.heroMessage.contains("SIMBROKER_CLI_PATH"),
+      "missing-CLI hero must not lead with SIMBROKER_CLI_PATH"
+    )
+    let fallback = BrokerMissingCLISetupCopy.manualFallbackText
+    let brewIndex = fallback.range(of: "Homebrew formula")?.lowerBound
+    let envIndex = fallback.range(of: "SIMBROKER_CLI_PATH")?.lowerBound
+    XCTAssertNotNil(brewIndex)
+    if let brewIndex, let envIndex {
+      XCTAssertLessThan(brewIndex, envIndex)
+    }
+  }
+
   func testRepoGuideUsesQuotedAbsoluteCLIPathWhenAvailable() {
     let guide = RepoOnboardingCommandGuide(
       cliPath: "/tmp/custom broker/simbroker",

broker-core/index.mjs

@@ -1064,10 +1064,13 @@ function selectRuntimeForAlias(simctl, iosVersion) {
     .sort((left, right) => compareVersions(right.version, left.version));
 
   if (runtimes.length === 0) {
-    throw new BrokerError(`No available iOS runtime matched ${iosVersion}.`, {
-      iosVersion,
-      reasonCode: "runtime-not-found",
-    });
+    throw new BrokerError(
+      `No available iOS runtime matched ${iosVersion}. Pass --ios-version to match an installed runtime from \`xcrun simctl list runtimes\`.`,
+      {
+        iosVersion,
+        reasonCode: "runtime-not-found",
+      },
+    );
   }
 
   return runtimes[0];

broker-core/test/broker-core.test.mjs

@@ -814,6 +814,51 @@ test("host init can bootstrap a starter host config when none exists yet", () =>
   assert.ok(simctlState.devices.some((device) => device.name === "Simulator Broker bootstrap-host manual-1"));
 });
 
+test("host init --bootstrap-config names --ios-version when no runtime matches the starter iOS version", () => {
+  const root = makeTempDir();
+  const simctl = createSimctlFixture(root, {
+    runtimes: [
+      {
+        identifier: "com.apple.CoreSimulator.SimRuntime.iOS-26-0",
+        isAvailable: true,
+        supportedDeviceTypes: [
+          {
+            identifier: "com.apple.CoreSimulator.SimDeviceType.iPhone-16",
+            name: "iPhone 16",
+            productFamily: "iPhone",
+          },
+          {
+            identifier: "com.apple.CoreSimulator.SimDeviceType.iPad-A16",
+            name: "iPad (A16)",
+            productFamily: "iPad",
+          },
+        ],
+        version: "26.0",
+      },
+    ],
+  });
+  const resolvedPaths = resolveBrokerPaths({
+    hostConfigPath: path.join(root, "host-config.json"),
+    stateRoot: path.join(root, "state"),
+  });
+
+  try {
+    initBroker(resolvedPaths, {
+      bootstrapConfig: true,
+      hostId: "missing-runtime-host",
+      processExists: () => true,
+      simctlAdapter: simctl.adapter,
+    });
+    assert.fail("expected runtime-not-found");
+  } catch (error) {
+    assert.equal(error instanceof BrokerError, true);
+    assert.equal(error.payload.reasonCode, "runtime-not-found");
+    assert.match(error.message, /--ios-version/);
+    assert.match(error.message, /xcrun simctl list runtimes/);
+    assert.match(error.message, /\b18\b/);
+  }
+});
+
 test("host init warns before creating bootstrap simulators", () => {
   const paths = makePaths();
   const resolvedPaths = brokerPaths(paths);

broker-core/test/support/simctl-fixture.mjs

@@ -65,9 +65,13 @@ export function createDeviceRecord({
   };
 }
 
-export function createSimctlFixture(root, { devices = [] } = {}) {
+export function createSimctlFixture(root, { devices = [], runtimes } = {}) {
   const statePath = path.join(root, "simctl-state.json");
-  writeJson(statePath, defaultSimctlFixtureState({ devices }));
+  const state = defaultSimctlFixtureState({ devices });
+  if (runtimes !== undefined) {
+    state.runtimes = runtimes;
+  }
+  writeJson(statePath, state);
   return {
     adapter: createFixtureSimctlAdapter({ statePath }),
     env: {

client/command-dispatch.mjs

@@ -617,6 +617,7 @@ function helpPayload(group) {
       ],
       notes: [
         "host init --bootstrap-config creates real iOS Simulator devices on this Mac.",
+        "If no iOS runtime matches the requested version, pass --ios-version from `xcrun simctl list runtimes`. Default starter iOS is 18.",
       ],
       group: "host",
       usage: "simbroker host <command>",

client/test/simbroker.test.mjs

@@ -324,6 +324,42 @@ test("host init can bootstrap a starter host config on a fresh machine path", ()
   assert.equal(result.json.bootstrapWarning, HOST_BOOTSTRAP_DEVICE_WARNING);
 });
 
+test("host init --bootstrap-config reports runtime-not-found with --ios-version guidance", () => {
+  const root = makeTempDir();
+  const fixture = {
+    hostConfigPath: path.join(root, "host-config.json"),
+    simctl: createSimctlFixture(root, {
+      runtimes: [
+        {
+          identifier: "com.apple.CoreSimulator.SimRuntime.iOS-26-0",
+          isAvailable: true,
+          supportedDeviceTypes: [
+            {
+              identifier: "com.apple.CoreSimulator.SimDeviceType.iPhone-16",
+              name: "iPhone 16",
+              productFamily: "iPhone",
+            },
+            {
+              identifier: "com.apple.CoreSimulator.SimDeviceType.iPad-A16",
+              name: "iPad (A16)",
+              productFamily: "iPad",
+            },
+          ],
+          version: "26.0",
+        },
+      ],
+    }),
+    stateRoot: path.join(root, "state"),
+  };
+
+  const result = runCli(fixture, "host", "init", "--bootstrap-config", "--host-id", "cli-missing-runtime");
+  assert.notEqual(result.status, 0);
+  assert.equal(result.json.ok, false);
+  assert.equal(result.json.reasonCode, "runtime-not-found");
+  assert.match(result.json.error, /--ios-version/);
+  assert.match(result.json.error, /xcrun simctl list runtimes/);
+});
+
 test("host init --bootstrap-config warns on stdout-adjacent stderr before devices exist", () => {
   const root = makeTempDir();
   const fixture = {