Add guided simbroker setup

CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Guided, deterministic `simbroker setup` preview and confirmed apply for
+  prerequisite checks, newest-compatible runtime selection, the six-device
+  starter pool, atomic provisioning, `brokerd` startup, snapshot refresh, and
+  health verification.
+- A macOS setup-plan sheet with all six aliases, runtime/build and disk details,
+  remediation commands, exact plan confirmation, cooperative Stop, and
+  cancellation-aware task ownership.
+
+### Changed
+
+- New project scaffolds require an iPhone for UI purposes without pinning an
+  iOS version unless `--ios-version` is explicit.
+- Homebrew CLI and app metadata now require macOS 14 Sonoma, matching the app
+  deployment target.
+- Newcomer documentation and install/package smoke tests use `simbroker setup`;
+  `host init --bootstrap-config` remains an advanced compatibility command.
+
 ## [0.1.0-alpha.2] - 2026-08-20
 
 This tag is the first Homebrew CLI tarball, npm tarball, and notarized

Casks/simulator-broker.rb

@@ -7,7 +7,7 @@
   desc "macOS operator app for the local iOS Simulator control plane"
   homepage "https://github.com/fiveonecode/simulator-broker"
 
-  depends_on macos: :ventura
+  depends_on macos: :sonoma
 
   app "Simulator Broker.app"
 

Formula/simbroker.rb

@@ -5,7 +5,7 @@ class Simbroker < Formula
   sha256 "f4b8740ff21ce6e7c6a3544e2811c1836d7132aaf3682d9e1c071732c80c7abe"
   license "MIT"
 
-  depends_on :macos
+  depends_on macos: :sonoma
   depends_on "node"
 
   def install

README.md

@@ -27,10 +27,15 @@ If you only ever use one simulator by hand, you may not need this yet.
 
 ## Use it
 
-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.
+Install the Homebrew CLI and optional operator app, then run one guided machine
+setup. Homebrew does not create Simulator devices. `simbroker setup` first
+shows every prerequisite, the selected runtime, and the exact six-device plan;
+nothing changes until you confirm it. Node.js 20+ is still required at runtime.
+
+> **Next Alpha availability:** guided `simbroker setup` is currently available
+> from `main` and source installs. The published `0.1.0-alpha.2` Homebrew, npm,
+> and cask artifacts predate this command; use the clone installer below to try
+> it now, or wait for the next Alpha release.
 
 ```bash
 brew install fiveonecode/simulator-broker/simbroker
@@ -49,18 +54,20 @@ 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:
+Open `Simulator Broker.app` and click **Complete first-time setup**, or use the
+same guided CLI flow:
 
 ```bash
-simbroker host init --bootstrap-config
-simbroker service start
+simbroker setup
 ```
 
-`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.
+The preview automatically selects the newest installed iOS runtime compatible
+with both iPhone and iPad, lists all six aliases as **Create** or **Reuse**, and
+asks once before provisioning. It then writes host configuration atomically,
+starts `brokerd`, refreshes the app snapshot, and verifies health. Rerun
+`simbroker setup` after an interruption; it safely finishes later stages without
+duplicating devices. For automation, use `simbroker setup --json`, then apply
+the returned `planId` with `--apply --confirm <plan-id> --json`.
 
 Other CLI install options:
 
@@ -112,8 +119,7 @@ keep the `agent:context` / `agent:verify` / `agent:complete` track.
 
 ## Five-minute hello world
 
-After the CLI resolves and this Mac has a host config from the first-run step
-above:
+After `simbroker setup` reports ready:
 
 ```bash
 mkdir -p /tmp/sample-broker-repo && cd /tmp/sample-broker-repo

app/README.md

@@ -82,6 +82,13 @@ You can also deep-link the initial operator surface for deterministic QA or hand
 ./script/build_and_run.sh -- --state-root /tmp/simbroker-fixture/state --pane simulators --simulator-alias ui-2
 ```
 
+An explicitly isolated broker socket can travel with the same launch context;
+the app forwards it unchanged to guided setup preview and apply:
+
+```bash
+./script/build_and_run.sh -- --state-root /tmp/simbroker-fixture/state --service-socket /tmp/simbroker-fixture/brokerd.sock
+```
+
 You can also launch the app binary directly with an environment override:
 
 ```bash