stim 1.18.0 → 1.20.0

package/dist/{guide-tm6igAaa.mjs → guide-Dai9lphv.mjs}

@@ -1,8 +1,9 @@
-import { s as findProjectRoot$1 } from "./project-C3ChRLZy.mjs";
-import { t as RECENT_LAUNCH_MS } from "./status-Dcr0Qexd.mjs";
-import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-CQyMElEP.mjs";
-import { t as guideStatus } from "./guide-status-Bhf9SJXc.mjs";
-import { SETTINGS, SETTINGS_SCHEMA_URL } from "@stim-cli/core/state";
+import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-Bbztm4oV.mjs";
+import { r as findProjectRoot } from "./project-B8_duAzW.mjs";
+import { s as RECENT_LAUNCH_MS } from "./watchman-CQl51YZu.mjs";
+import { o as guideStatus, t as WATCHMAN_NESTED_WORKTREES } from "./doctor-watchman-CB4NnVZm.mjs";
+import "./status-watch-DvmI3SmN.mjs";
+import { SETTINGS, SETTINGS_SCHEMA_URL, TUTORIAL_VERSION } from "@stim-cli/core/state";
 import chalk from "chalk";
 //#region src/guide/agent.ts
 var agent_default = {
@@ -14,6 +15,9 @@ device with another workspace. Prefer plain output: it streams each phase and
 ends with the facts the next step needs. Use --json only when a script must
 parse a stable payload.
 
+For a native Xcode or Gradle app without React Native or Expo, read guide
+lifecycle native-ios or guide lifecycle native-android before running it.
+
 TWO WORKFLOWS
 
 WORKTREE is the default. Take SINGLE CHECKOUT only when the user asks to work in
@@ -91,7 +95,10 @@ the printed remedy and keep concurrent runs on the same STIM_HOME.
 Before native work, run doctor for the platform in scope when the STATUS block
 at the top of this topic says it is due. No block means doctor is current and
 Stim is up to date. In the worktree workflow, run it from the linked worktree
-so it also checks the source checkout. Follow each finding's printed remedy,
+so it also checks the source checkout. Doctor never loads fingerprint.config.js
+or runs an eas from the project tree; its fingerprint checks can still run
+installed Expo packages, including hoisted ones, as a build does. warm,
+start, ios and android run project code. Follow each finding's printed remedy,
 and read the routed topic below before acting on one you do not understand. If
 the stim resolved from PATH is older than another installation, fix PATH or the
 installation before continuing so commands and guidance match. Under host
@@ -405,7 +412,7 @@ FULL TOPIC LIST
 //#endregion
 //#region src/guide/api.ts
 var api_default = {
-	summary: "Typed lifecycle API: createStim, run, stop, diagnostics, and cancellation",
+	summary: "Typed lifecycle API: createStim, build, run, stop, diagnostics, and cancellation",
 	body: () => `PROGRAMMATIC API
 
 Install stim as a project dependency: npm install --save-dev stim.
@@ -435,8 +442,27 @@ run takes platform plus its options:
   macos:   remoteBuild
   web:     headed (default false)
 iOS and Android also accept slot, metroCheck, buildCache, and remoteBuild.
-All methods accept signal. run builds, installs and launches; build-only is
-not available. Web requires a running server, just like stim web.
+All methods accept signal. run builds, installs and launches.
+Web requires a running server, just like stim web.
+
+build produces an artifact without acquiring a device, starting a runtime, or
+stopping an existing session. Its result is inferred from platform:
+  const result = await stim.build({ platform: 'ios' });
+  console.log(result.facts.appPath);
+
+Build options:
+  ios:     scheme, configuration, arch (arm64, x86_64, all), buildCache, remoteBuild
+  android: variant, abi (arm64-v8a, armeabi-v7a, x86, x86_64, all), buildCache, remoteBuild
+  macos:   remoteBuild
+An iOS build targets the simulator. A Debug build defaults to the host
+architecture (Android only while optimizations.android.targetAbiOnly is on, the
+default); Release defaults to all. macOS builds the configured Debug SwiftPM app.
+Build results retain an owned appPath (iOS), apkPath (Android) or bundle (macOS)
+inside this workspace until worktree removal. Later builds keep earlier copies.
+A build leaves a running app's last build record and build log untouched; it
+writes its own build-artifact-<platform>.ndjson. No distribution archive or web build
+pipeline is inferred. Use @stim-cli/ci's buildCI to export a portable artifact and
+diagnostics for your CI provider.
 
 run returns { platform, facts }. iOS facts include udid; Android includes
 serial; both include bundleId, appPath, metroPort, cacheHit and launched.
@@ -518,7 +544,9 @@ worktree, carries git:
                null when git fails or does not answer within 3 s, or the
                worktree has no environment and sits in ~/Desktop, ~/Documents,
                ~/Downloads, iCloud Drive, ~/Library/CloudStorage or /Volumes,
-               which status does not open on macOS
+               which status does not open on macOS; one-shot status also
+               leaves it null for a worktree with no live environment and
+               for every unprovisioned worktree
   changed      tracked paths with staged or unstaged changes, conflicts included
   untracked    untracked entries as git status lists them; a new directory
                counts once
@@ -528,16 +556,17 @@ worktree, carries git:
   mergedInto   "origin/<default>" when gc would call the branch merged, judged
                from local refs without fetching, else null
 
-status runs \`git status --porcelain=v2 --branch\` in every worktree in
-parallel, and caches the merge verdict by HEAD and default-branch commit
+status runs \`git status --porcelain=v2 --branch\` in the worktrees it reads,
+six git calls at a time, and caches the merge verdict by HEAD and default-branch commit
 under $STIM_HOME/git-merge. One call starts no new merge check 250 ms after
 its first; later calls judge the rest, and until then a verdict for the same
 HEAD at an older default-branch commit stands in; a check that timed out
 is retried after 5 minutes. \`status --watch\` reuses a worktree's git read
 until its index, HEAD, reflog or the branch, upstream or default-branch refs
 change, and for at most 60 s, so a file edit, creation or deletion that is
-not staged can take up to a minute to show. Plain status prints "git: 2 changed, 1 untracked, ahead 3" under
-each environment, and the same after each worktree with no environment.
+not staged can take up to a minute to show. One-shot status reads git only
+for live environments; \`status --watch\` reads every worktree. Plain status prints "git: 2 changed, 1 untracked, ahead 3" under
+each environment it read, and the same after each worktree with no environment under \`--watch\`.
 
 The paired phone's Work sheet can open changed and untracked files when the
 server advertises workspace-diff. File lists and selected patches load on
@@ -632,7 +661,8 @@ leased until <time>" for each one.`,
   port            the Metro port RESERVED for this workspace
   supervisorPid   the detached supervisor's pid, or NULL when a dev server was
                   already answering that Stim did not start
-  mode            "bare-inproc" | "expo-child" | null (see \`guide metro\`)
+  mode            "bare-inproc" | "expo-child" | "command-child" | null
+                  (see \`guide metro\`)
   logsDir         where the NDJSON timeline is written
   agentDevice     { stateDir }: absolute workspace agent-device state path;
                   set AGENT_DEVICE_STATE_DIR to it (see guide logs)
@@ -696,8 +726,9 @@ leased until <time>" for each one.`,
   configuration   the Xcode configuration that was built ("Release" from
                   --configuration or the ios.configuration setting); null for
                   the default Debug
-  scheme          the explicit shared Xcode scheme selected by --scheme;
-                  absent for automatic selection; not the app URL scheme
+  scheme          the explicit shared Xcode scheme selected by --scheme or
+                  the ios.scheme setting; absent for automatic selection;
+                  not the app URL scheme
   cacheKey        the shared-build-cache key derived from it (the
                   configuration is part of it: -release-sim vs
                   -debug-sim-arm64). A single-architecture simulator build
@@ -757,8 +788,11 @@ leased until <time>" for each one.`,
                   the bundle would cost more than installing it
   launched        true, "bundling", or "unverified". THE THREE ARE DIFFERENT
                   FACTS and only the last one is a problem.
-                    true         Metro finished the bundle response, then the app stayed
-                                 alive through a three-second stability window.
+                    true         Metro finished the bundle response, or an app
+                                 without Metro (a release build, or a native
+                                 Xcode or Gradle app) has a live process; then
+                                 the app stayed alive through a three-second
+                                 stability window.
                                  The command checks process liveness when the
                                  platform exposes it. Errors from that window
                                  are printed even when the app stays alive,
@@ -1013,6 +1047,9 @@ leased until <time>" for each one.`,
                   optional fields
   findings        the diagnostic findings; a lower resolved Stim is a
                   costs-time finding with a PATH or installation remedy
+                  memory-culprit is a costs-time finding naming a process
+                  with an abnormally large footprint and, when it is safe to
+                  restart, the command
                   offload-candidate is a note after 3+ successful local cold builds in 7 days average over 3 min, with no remote.machines and an online tailnet Mac; open Stim Desktop Settings > Remote Macs > Add
 
 ON FAILURE
@@ -1432,8 +1469,9 @@ RULES
 			body: () => `  stim status --json
 
   logs        { dir, errorsSinceMarker }, or null without a log directory
-  agentDevice { stateDir }: absolute workspace agent-device state path on
-              every environment, shared by its slots. Reporting it creates
+  agentDevice { stateDir, installed }: absolute workspace agent-device state
+              path on every environment, shared by its slots, and whether
+              the agent-device executable is on PATH. Reporting it creates
               no directory; agent-device creates it when used.
 
   Each environment carries phase, where the workspace is in its lifecycle:
@@ -1463,6 +1501,9 @@ RULES
               of the Stim tutorial app (stim guide tutorial). Status
               reports whatever version it finds; Desktop decides which
               versions it supports. Static app.json only.
+  doctorRuns  { ios?: { at }, android?: { at } }: when stim doctor last
+              ran in the workspace, per platform, as ISO timestamps;
+              absent until it has run.
   recording   { enabled }: whether stim-server may record the workspace's
               device screens for replay, from recording.enabled
 
@@ -1732,8 +1773,8 @@ RULES
   build   { platform, slot, state, phase, startedAt, phaseStartedAt,
             outcome, outcomeKnown, cacheLookupOutcome?, expectedMs, expectedPhaseMs,
             completedPhaseMs?, basis,
-            plannedPhases, missReason?, missProvisional?, detail?, placement,
-            waitingOn?, waitingFor? }
+            plannedPhases, missReason?, missProvisional?, detail?, activity?,
+            placement, waitingOn?, waitingFor? }
 
   state            "running" while the run's own native-run claim is live;
                    "stale" when that claim was released or its process is
@@ -1749,7 +1790,10 @@ RULES
                    once the app is ready and covers waiting for the
                    device: its boot, adoption cleanup, or a physical
                    device's lease and connection check. A boot that
-                   finishes during the build adds no device time. An
+                   finishes during the build adds no device time. For a
+                   device hosted on another Mac, device covers reserving
+                   and preparing it there, install covers delivering the
+                   app, and launch starts when the host launches it. An
                    --eas-profile run has no cache lookup, so its outcome
                    stays the project's most recent one until install.
                    A stim macos run enters only prepare, compile (SwiftPM,
@@ -1822,6 +1866,16 @@ RULES
                    to file names, at most 160 characters
     updatedAt      when the build last wrote it; the run writes it at most
                    every 2 seconds
+  activity         during device or launch, once Stim observed what the run
+                   waits on: { name, startedAt, percent? }. name is
+                   "booting" while device waits for the owned simulator or
+                   emulator the run is booting; during launch, "bundling"
+                   from the app's bundle request to this workspace's Metro
+                   until Metro delivered it, or "waiting-ready" while the
+                   app reports its readiness pending; absent in between.
+                   startedAt is the evidence's time. percent is Metro's own
+                   progress for that request, present only once Metro
+                   reported one. Activity never changes launched.
   placement        where the build runs: "local", or while it is offloaded
                    { host, phase, startedAt, phaseStartedAt }. host is the
                    remote.machines entry; phase is the step there: sync,
@@ -1842,6 +1896,7 @@ RULES
 
     build: ios compile, 1m10s elapsed -- about 3 min left (median of 4 cold runs)
     build: ios compile on janics-mac-mini (build, 2m10s), 3m05s elapsed
+    build: ios launch (bundling JS 45%, 12s), 58s elapsed
 
   An environment with a recorded run also carries lastBuilds, each
   platform's most recent ios or android run, finished or failed:
@@ -1942,7 +1997,8 @@ RULES
   disk (environment)  { worktreeBytes, nodeModulesBytes, buildBytes,
                       measuredAt }
     worktreeBytes     the linked worktree, or else the checkout holding the
-                      workspace, node_modules included
+                      workspace, node_modules included; the linked
+                      worktrees nested inside a checkout are not counted
     nodeModulesBytes  node_modules at that root and at the workspace path;
                       part of worktreeBytes
     buildBytes        Stim's folder for the workspace: Xcode derived data,
@@ -1952,11 +2008,13 @@ RULES
   disk (device)       { bytes, measuredAt }: the simulator's data folder
                       under CoreSimulator/Devices, or the AVD's .avd folder
 
-  \`status --watch\` runs one du at a time off its refresh path, and measures
-  a folder at most every 5 minutes while its environment is active and every
-  hour otherwise. It caches each size under $STIM_HOME/disk-usage, which
-  one-shot status only reads, so the fields appear once a watcher, such as
-  stim-server or Stim Desktop, has measured.
+  \`status --watch\` runs one du at a time on the whole machine, at low
+  priority, off its refresh path, and measures a folder at most every 5
+  minutes while its environment is active and every hour otherwise. A walk
+  that fails or times out is not repeated by any watcher for that period. It
+  caches each size under $STIM_HOME/disk-usage, which one-shot status only
+  reads, so the fields appear once a watcher, such as stim-server or Stim
+  Desktop, has measured.
 
   An environment carries agents when coding-agent sessions work in it, most
   recently active first:
@@ -2018,7 +2076,9 @@ RULES
   builds included, when machine.memorySource is footprint. Otherwise it is
   the estimate, with memorySource estimate.
 
-  capacity.committedMb sums memoryMb. The memory budget plans before a boot
+  capacity.committedMb sums memoryMb; in a \`status --watch --json\` line each
+  figure, including an environment's memoryMb, is held on its own (see
+  \`guide lifecycle\`), so the sums can differ from what they sum. The memory budget plans before a boot
   and always uses the estimate. What is using CPU and memory now is the
   top-level machine section:
 
@@ -2252,8 +2312,9 @@ HOW A RUN IS COUNTED (\`stats\`)
 
 DEVICE PLACEMENT (\`ios|android --remote auto\`)
   Auto runs include devicePlacement: { decision, reason, machine? } in the run
-  facts, lastBuilds and build history. decision is "local", "hosted" or
-  "waited-locally" (the local run actually waited for a device slot). The same
+  facts, lastBuilds and build history. decision is "local", "hosted",
+  "waited-locally" (the local run actually waited for a device slot) or "eas"
+  (remote.easFallback put it on an EAS Simulator, reported like --remote eas). The same
   optional devicePlacement appears on the status device entry for each slot.
   Hosted host facts include selected: "auto" or the named machine, and reason
   for automatic placement. Plain status prints (auto: <reason>) after the host.
@@ -2433,8 +2494,9 @@ WHAT THE SUPERVISOR IS
   to install, and no cross-project state. It hosts the dev server, writes its
   output as NDJSON into the global workspace logs directory
   ($STIM_HOME/workspaces/<project>--<digest>/logs; see \`guide logs\`), and
-  records itself in that workspace's state.json before it starts serving. Two modes,
-  chosen by ecosystem detection:
+  records itself in that workspace's state.json before it starts serving. Three
+  modes: metro.command selects command-child, otherwise ecosystem detection
+  picks one of the first two:
 
     bare-inproc  bare React Native: Metro is hosted INSIDE the supervisor,
                  from the project's own node_modules, with Stim's reporter
@@ -2443,6 +2505,15 @@ WHAT THE SUPERVISOR IS
     expo-child   Expo: the project's own \`expo start --port <port>\` runs as
                  a child and its stdout is parsed into records. Levels are
                  INFERRED from each line, so those records carry raw: true.
+    command-child  metro.command (\`guide settings\`): that argv runs as a
+                 child in its own process group, with {port} replaced by the
+                 reserved port, and its output is parsed like expo-child's
+                 under command_stdout and command_stderr events. Stopping the
+                 dev server signals the whole group, so a wrapper such as
+                 yarn takes its Metro with it. Stim adds no reporter, warmup
+                 observer or shared transform store, so ios and android
+                 launches stay UNVERIFIED: read \`stim logs --source metro\`
+                 for the bundle lines.
 
   In expo-child mode, remote intent plus metro.tunnel "expo" makes \`start\` pass
   \`--tunnel\` and EXPO_UNSTABLE_TUNNEL_V2=1 (the legacy ws-tunnel path is
@@ -2461,7 +2532,8 @@ WHAT THE SUPERVISOR IS
 
   IDLE STOP: the supervisor stops its dev server after metro.idleStopMinutes
   (default 60; 0 never stops) with no bundle request, no client log record
-  (in-app console logs; for Expo, any stdout line of the Expo CLI) and no Stim
+  (in-app console logs; for Expo or metro.command, any stdout line of the
+  dev server) and no Stim
   command in the workspace (start, ios, android, reload, worktree warm). It
   checks once a minute. It keeps running while a bundle response is in
   flight, while a build in the workspace is in progress, while a stim ios,
@@ -2600,9 +2672,15 @@ then 8081, without probing or reserving; an invalid pin still refuses.
 
 New allocations scan TCP ports 8900-8999. They skip registry reservations
 and existing listeners, announcing occupied ports and upward retries on
-stderr. Listener checks require lsof, or netstat on Windows. All 100 ports
-occupied or reserved is a refusal; stop or release unused allocations in
-their owning workspaces.
+stderr. All 100 ports occupied or reserved is a refusal; stop or release
+unused allocations in their owning workspaces.
+
+Metro allocation (from 8082 up) and named allocation find listeners in the
+native TCP table: netstat on macOS and Windows, /proc/net on Linux. When that
+table is denied, empty or unreadable, as in some sandboxes, each candidate is
+checked with an lsof listener scan and connects to 127.0.0.1 and ::1 instead.
+Allocation refuses only when none of them can answer: start refuses with
+STIM_PORT_INSPECTION_FAILED, and ports get prints the same message.
 
 The machine registry, under STIM_HOME, serializes allocation and cleanup.
 The workspace is the nearest package.json directory, resolved through
@@ -2625,6 +2703,7 @@ ports lists named labels and ports, plus Metro marked managed.
 ports stop [label] kills TCP listeners on those named ports and releases
 the allocations. It sends SIGTERM, waits two seconds, then SIGKILL if needed;
 on Windows it terminates the listener's process tree with taskkill.
+Stopping listeners requires lsof on macOS and Linux, or netstat on Windows.
 It prints the PID and command (the image name on Windows) for each stopped
 process. The listener's cwd can be anywhere: the named reservation is
 permission to stop that listener.
@@ -2635,11 +2714,12 @@ ports release [label] releases without signalling a process.
 Omitting the label selects every named port, never Metro. stim stop leaves
 named ports alone.
 
-worktree remove stops named listeners and releases their allocations.
-gc reports allocations whose workspace no longer exists; gc --delete stops
-and releases them. Unmounted or unresolved workspace paths are retained.
-Failed stops keep the registry entry. Use the same current Stim version for
-cleanup: versions without ports do not know about named allocations.
+worktree remove, gc --delete and automatic maintenance release named
+allocations without signalling their listeners; run ports stop first to stop
+a server this workspace started. gc reports allocations whose workspace no
+longer exists; gc --delete releases them. Unmounted or unresolved workspace
+paths are retained. Use the same current Stim version for cleanup: versions
+without ports do not know about named allocations.
 
 A shared API does not get a shared reservation. Pass its port by environment
 instead of allocating a separate label in every worktree.`
@@ -2864,7 +2944,8 @@ THE RECORD
     clockOffsetMs the offset added to deviceTs; absent if the query failed.
              A collector_clock warning then says timestamps retain device time.
     raw      true when the level was inferred from a line of text rather than
-             reported by the producer (every expo-child record)
+             reported by the producer (every expo-child and command-child
+             record)
     context  --errors --json only: the code frame and stack lines Expo
              printed after this error, as an array of strings. Absent when
              there are none. Stim adds it at query time; it is not in the
@@ -2915,27 +2996,31 @@ remote Mac and a named --remote target write none:
   stim logs --source placement --json
 Fields: kind (build or device), platform, settings [{ key, value, from }] with
 from flag, env, setting or default (remote.build and remote.buildMode for a
-build, ios.remote or android.remote for a device), candidates [{ machine, code,
+build, ios.remote or android.remote, plus remote.easFallback when it is on, for
+a device), candidates [{ machine, code,
 msg, detail? }], choice { machine, code, msg } with machine local when the run
 stays on this Mac, and fallback { code, msg, machine? } when a remote Mac that
 was meant to take the run did not (level warn). The msg is the same text the
 placement: and build: phase lines print.
 Candidate codes: accepted, unreachable, busy, disk, load, version-mismatch
 (detail lists the toolchain parts: xcode, arch, jdk, ...), no-matching-device,
-declined, memory, no-capacity. Choice codes for a build: placed, named,
+declined, memory, no-capacity; with machine eas, why an EAS Simulator was not
+used: eas-named-slot, eas-local-flags, eas-no-agent-device, eas-no-cli,
+eas-cli-too-old, eas-session-busy, eas-metro-unreachable, eas-logged-out, eas-not-enabled,
+eas-unavailable. Choice codes for a build: placed, named,
 forced, this-mac-busy, this-mac-free, mode-off, local-selected, no-remote-mac,
 unsupported; fallback codes: no-remote-mac-took-it, offload-failed, fallback.
 Choice codes for a device: placed, sticky, this-mac-free, no-remote-mac,
-device-count-unknown, no-host-admits. Machine names appear in these records;
+device-count-unknown, no-host-admits, eas-fallback (machine eas). Machine names appear in these records;
 they stay in the local logs. These records carry no tokens.
 
 WHAT WRITES WHAT
   maintenance.ndjson   workspace maintenance actions, failures and explaining skips
-  metro.ndjson         the bundler, in both supervisor modes
+  metro.ndjson         the bundler, in every supervisor mode
   client.ndjson        in-app console logs and redboxes -- BARE PROJECTS ONLY.
-                       In expo-child mode everything Expo prints lands in
-                       metro.ndjson with raw: true, so \`--source client\`
-                       returns nothing there.
+                       In expo-child and command-child mode everything the
+                       dev server prints lands in metro.ndjson with raw: true,
+                       so \`--source client\` returns nothing there.
   device.ndjson        the device-log collector uses \`simctl log stream\`
                        predicated on the app, or \`adb logcat\` filtered to
                        the app's pid. Local iOS simulator capture starts
@@ -3098,7 +3183,9 @@ WHAT WRITES WHAT
   build-android.ndjson extracted diagnostics at level error, and the launch as
                        a marker record. One RUN's worth: each build starts the
                        file over, so the first error in it always belongs to
-                       the run that pointed you at it.
+                       the run that pointed you at it. A build from the API's
+                       build() writes build-artifact-<platform>.ndjson
+                       instead, so it never replaces a run's transcript.
 
   Only a dev server Stim hosted is captured. If you started the bundler
   yourself, the metro and client sources stay empty -- which is not a sign of a
@@ -3440,9 +3527,14 @@ Branch on the code, never on the message.`,
   works. See stim guide macos.`
 		},
 		STIM_OFFLOAD_REFUSED: {
-			summary: "the selected remote Mac cannot build this app",
+			summary: "the selected remote Mac or automatic build pool cannot build this app",
 			body: () => `STIM_OFFLOAD_REFUSED
 
+Automatic placement also refuses when local is excluded in remote.buildPoolDisabled
+and no enabled remote can finish this build, or when the build requires a local
+compiler. Enable local or choose an explicit --remote-build placement. Existing
+builds are not interrupted and a cache hit needs no compiler.
+
 A named --remote-build selection is strict. The message names the machine
 and why it cannot take or finish the build: not configured or paired, approval
 pending or denied, unreachable or changed pinned identity, incompatible
@@ -3555,7 +3647,8 @@ Rerun with --remote-build auto for normal placement and local fallback, or
 			body: () => `STIM_NO_SCHEME
   Stim could not list or select an app scheme in ios/. Share the intended app
   scheme so xcodebuild can see it. Select an available exact name with
-  \`stim ios --scheme <name>\`. An unknown explicit name prints available choices.
+  \`stim ios --scheme <name>\`, or set it once with the ios.scheme setting. An
+  unknown explicit name prints available choices.
   Without an explicit selector, a workspace
   name match wins; otherwise Stim accepts a sole non-test scheme, or a listed
   scheme matching app.json. Unmatched ambiguous schemes are refused.`
@@ -3888,7 +3981,9 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   physical, hosted, remote, parked and other homes' devices and never deletes.
   A failed reclaim is logged and skipped; the run keeps waiting.
   Stop an environment (\`stim stop\`), pass a longer \`--wait <seconds>\`,
-  or raise concurrency.maxDevices. Waiting prints holder names and elapsed
+  or raise concurrency.maxDevices. With --remote auto, remote.machines and
+  the opt-in remote.easFallback (billed EAS Simulator) are tried before this
+  wait; \`stim logs --source placement\` says why neither took the run. Waiting prints holder names and elapsed
   time; status JSON exposes build.waitingFor independently of phase.
   Stats records capacityWaits for waits and capacityRefusals for this code.
   See \`guide lifecycle concurrency\`.`
@@ -4175,6 +4270,17 @@ captured"  (in metro.ndjson, bare RN)
   printed the last lines of the global workspace logs/supervisor.log above this -- read
   them. A cold Metro on a large graph can genuinely need more than the default
   60s: re-run with \`--wait 180\`. Otherwise \`stim stop\`, then \`start\`.`
+		},
+		STIM_PORT_INSPECTION_FAILED: {
+			summary: "no free Metro port could be confirmed: netstat, lsof and loopback connects all failed",
+			body: () => `STIM_PORT_INSPECTION_FAILED
+  Stim reads the native TCP listener table (netstat on macOS and Windows,
+  /proc/net on Linux) to find a free Metro port. When that table is denied,
+  empty or unreadable, it checks each candidate with an lsof listener scan and
+  connects to 127.0.0.1 and ::1. This refusal means none of them could answer,
+  usually because a sandbox denies them. Allow Stim to run netstat or lsof, or
+  to connect to loopback, then retry. A metro.port pin skips the scan for
+  Metro. \`stim ports get\` prints the same message.`
 		},
 		STIM_SUPERVISOR_EXITED: {
 			summary: "the dev server failed outright; the quoted supervisor.log tail is the real error",
@@ -4218,10 +4324,10 @@ captured"  (in metro.ndjson, bare RN)
   \`--device-profile\` on an eas/proxy run (\`--remote\` or android.remote), a
   \`android --remote auto\`, a changed hosted placement, or hosted Debug
   with \`--no-metro-check\` (see lifecycle hosted-android), a working directory
-  with no package.json above it, or one whose nearest package.json does not
-  parse or depends on neither react-native nor expo, so the directory is not
-  an app (the refusal names that package.json and says which of the two it
-  is; \`doctor\` reports the same directory as a finding), a \`logs\` query in
+  with no supported app project, or a project whose integration refuses this
+  operation. React Native and Expo require a readable package.json that
+  declares react-native or expo; the refusal names the invalid file.
+  \`doctor\` reports project admission problems as findings. A \`logs\` query in
   a workspace that has never produced a log timeline (the refusal names the
   nearest registered descendant app with logs when one exists), an
   android/app/build.gradle that declares product flavors with
@@ -4248,7 +4354,7 @@ captured"  (in metro.ndjson, bare RN)
   \`gc --json --cache <name>\` refuses with STIM_BAD_ARG when no shared cache
   carries the name; the remedy names the caches on this machine. \`gc\`
   refuses --cache together with --worktrees the same way.
-  A working directory with no package.json above it gets the same
+  A working directory with no supported project above it gets the same
   STIM_NO_PROJECT refusal from \`start\`, \`ios\`, \`android\`, \`stop\`,
   \`reload\`, \`logs\`, \`doctor\` and \`device lock|unlock\`. With \`--json\` the { code, message, remedy } object
   is on stdout, except \`logs --json\`, whose stdout stays empty NDJSON; the
@@ -4709,6 +4815,10 @@ const lifecycle = {
 	summary: "The full worktree -> start -> ios/android -> logs -> teardown flow, with sections for builds, devices and flags",
 	preamble: () => `ENVIRONMENT LIFECYCLE
 
+For a native Xcode or Gradle app without React Native or Expo, read
+\`stim guide lifecycle native-ios\` or \`stim guide lifecycle native-android\`.
+The Metro and JavaScript steps below apply to React Native and Expo.
+
 Two workflows share steps 2 through 6.
 
 SINGLE CHECKOUT: work in place, on a branch, in one directory. There is no
@@ -4784,7 +4894,7 @@ a seed belongs to this workflow.
   #    unwarmed worktrees with no Stim registry entry. Git-created branches stay.
   stim worktree remove
 
-A Debug \`ios\` or \`android\` run checks the reserved port before the device
+A React Native or Expo Debug \`ios\` or \`android\` run checks the reserved port before the device
 or the build. When no healthy dev server of this workspace answers there, it
 runs the same start as step 2: a dev server started outside Stim is reused, a
 reservation held by a foreign process moves to a free port, and the budgets
@@ -4948,7 +5058,10 @@ WAITING FOR A CHANGE
   To wait for a device, a build or a dev server instead of polling, run
   \`stim status --watch --json\`. It keeps running and prints one complete
   status payload per line: one at once, then one each time the payload
-  changes, never two identical ones in a row. It reacts to Stim state files,
+  changes, never two identical ones in a row. In a watch line, a usage
+  figure repeats its value in the previous line until it moves by a step: an owner's cpuPercent 5 points, an
+  owner's or environment's memoryMb and capacity.committedMb 16 MB. An owner's row
+  changes as a whole, so its residentMb and processes update with it. It reacts to Stim state files,
   the EAS session ledger, adb device arrivals and departures, and simulator
   state, and recomputes every 30 seconds as a fallback. A log append updates
   only the log error count and device activity, no sooner than 15 seconds
@@ -4959,6 +5072,161 @@ WAITING FOR A CHANGE
   still running, which it notices at the next change.
   Without --json it reprints the human view on change.`,
 	sections: {
+		"native-ios": {
+			summary: "native Xcode project selection, process launch, cache behavior and current limits",
+			body: () => `NATIVE XCODE APPS
+Run from the directory containing the .xcodeproj or .xcworkspace. A Node
+package.json is not required. React Native and Expo apps keep their existing
+integration.
+
+  stim doctor --platform ios
+  stim ios --scheme MyApp --configuration Debug --json
+  stim ios --scheme MyApp --configuration Release --json
+  stim logs --errors
+  stim stop
+
+Use the project's actual scheme and configuration names. Shared Run schemes
+select application targets; a unique application target can also use its
+automatic scheme. A workspace owns its referenced projects. --scheme selects
+an exact name; duplicate container/scheme matches refuse instead of guessing.
+--configuration overrides ios.configuration in .stim.json, then defaults to
+Debug. Custom configurations such as Staging use the same path.
+
+Native Debug, Release and custom configurations do not start or require Metro,
+embed JavaScript, or swap a JavaScript bundle. The app is launched as a native
+process and reports metroPort: null. launched: true establishes a live process;
+verify the expected screen and interaction on the reported device separately.
+After a native source edit, rerun stim ios. stim reload is for JavaScript.
+The existing owned simulator, device lease, signing, log and teardown services
+still apply. Stim does not change signing accounts or provisioning profiles.
+
+A reusable artifact key includes the selected build configuration, source and
+known dependency inputs, toolchain and build options. In a git checkout,
+ignored files the project does not reference are not part of the key. Native
+Release cache reuse does not depend on releaseBundleSwap. Xcode compilation
+uses the shared compilation cache when the toolchain and settings support it.
+--plan predicts this same local artifact without preparing dependencies or
+choosing a device.
+
+Inputs whose complete build closure cannot be established build locally with
+artifact caching skipped. This includes shell build phases, custom build rules,
+C-family header graphs, Swift package graphs and unresolved external input
+paths or compiler overrides. The miss reason explains the exclusion. --plan
+refuses such a prediction; omit --plan to prepare and build the app.
+
+A compatible approved build Mac can compile a native Xcode app with
+--remote-build auto or --remote-build <name>. Both peers must support
+native-xcode-build. This first worker path requires a verified artifact identity
+and all inputs contained in the repository and visible to git. Ignored or
+external inputs keep the build here, and placement names the first one; their
+bytes are never silently omitted. The common case is a Finder .DS_Store that a
+global gitignore hides: delete it, or stop ignoring it, to offload. The worker
+compares its own toolchain and compiler environment identity before compiling
+and refuses, naming the differing parameter, so the build falls back here.
+Worker source mirrors remove stale inputs, while Xcode compilation caches remain
+in the worker's private Stim home. Physical builds stay local.
+
+Native Xcode apps can install on an already approved hosting Mac with
+process-mode support:
+  stim ios --scheme MyApp --configuration Debug --remote janics-mac-mini --json
+
+The host must advertise hosted-ios-process; older hosts refuse with an update
+remedy before reservation or upload. --remote auto skips incompatible hosts,
+but an existing session stays on its recorded host until stim stop. Debug,
+Release and custom configurations use the offered simulator architecture,
+report metroPort: null, and close any previous session Metro bridge. Logs,
+view/control, agent access and scoped stop use the existing hosted-ios services.
+Verify UI and interaction separately from the host's live process evidence.
+
+Unbounded native build offload, hosted --plan, eas/proxy devices and EAS artifact
+profiles remain unsupported for native Xcode apps. These limits do not change React Native or
+Expo support.
+
+Copyable agent request:
+  Run this native Xcode app with stim ios --scheme MyApp --configuration Debug
+  --json. Verify its expected screen and interaction on the reported device,
+  inspect stim logs --errors, then stop only this workspace with stim stop.`
+		},
+		"native-android": {
+			summary: "native Gradle app selection, hosted emulators, build-worker inputs and current limits",
+			body: () => `NATIVE ANDROID GRADLE APPS
+Native Android Gradle apps run directly with \`stim android [--variant freeDebug]\`:
+no Metro, npm install or React Native dependency is required. The directory must
+contain a Gradle wrapper and settings.gradle or settings.gradle.kts. AGP resolves
+one application module and the exact variant (debug by default). Stim installs
+one signed universal or matching-ABI APK on an owned emulator or leased phone.
+Use \`--remote <approved-mac>\` or \`--remote auto\` for a hosted emulator; the host
+must support native Android process mode. Multiple application modules,
+density/split APK sets and EAS/proxy targets are unsupported. Set
+org.gradle.configureondemand=false; configuration cache remains supported.
+Stim verifies the existing APK signature; it does not sign it.
+
+Stim artifact caching is unavailable because arbitrary Gradle inputs are not fully
+tracked. Build workers require a project-scoped \`android.offloadInputs\` declaration:
+\`{"complete":true,"ignored":["app/src/main/assets/generated.json"],"outputs":["build","app/build"]}\`.
+Use \`stim android --remote-build <approved-mac>\` after reviewing this declaration.
+Paths are exact repository-relative paths. complete affirms that Git-visible
+source plus the listed ignored files suffice, including optional files; Gradle
+DSL can read undeclared input without failing. Never list secrets or user Gradle
+homes. External inputs, directory links, submodules and custom local.properties
+refuse; an SDK-only local.properties stays local. Only declared directories
+reported by AGP and previously produced by this worker remain warm, along with
+worker project .gradle/.kotlin state. Undeclared bytes are removed. Gradle owns
+incremental, task-cache and configuration-cache reuse; transfer digests never
+become reusable APK cache keys. Older hosts refuse before source upload.
+
+outputs must list every build directory of this build's projects that the build
+creates: the root build directory and each module's, library modules included.
+A remote build that creates an undeclared one fails with its name, and Stim
+builds locally; add it to outputs. A buildSrc directory refuses before upload.
+Included builds (includeBuild, such as a build-logic plugin build) and
+externalNativeBuild staging (.cxx) are not reported by AGP and cannot be
+declared, so a remote build that creates them fails and Stim builds locally.
+
+Native Android \`--plan\` refuses without executing Gradle; \`doctor\` reports native
+prerequisites. \`reload\` refuses because the app has no Metro runtime. Re-run
+\`stim android\` after an edit and use \`stim stop\` for scoped cleanup.`
+		},
+		ci: {
+			summary: "Run an app and tests through @stim-cli/ci with diagnostics and scoped cleanup",
+			body: () => `CONTINUOUS INTEGRATION
+
+Install app dependencies and platform tools first. Use a dedicated checkout:
+cleanup stops that workspace, including resources created before a build fails.
+
+  npx --yes --package @stim-cli/ci stim-ci run --platform ios --project ./app --timeout 1800 -- pnpm test:e2e
+
+Or install npm install --global @stim-cli/ci and use stim-ci directly.
+Platforms: ios, android, macos, web. Everything after -- is argv, not a shell.
+--artifacts selects the result directory (a fresh temporary directory by default).
+An explicit artifacts directory must be empty; use a new directory per run.
+Stdout is one JSON result; progress and test output go to stderr.
+
+Tests receive STIM_CI_PLATFORM, STIM_CI_DEVICE_ID, STIM_CI_APP_ID,
+STIM_CI_METRO_PORT, STIM_CI_ARTIFACTS_DIR and STIM_CI_RUN_RESULT. The last is
+run.json with the exact public API result. Use that target and check app
+readiness; launched can still be bundling or unverified.
+
+result.json preserves the test exit code even if diagnostics or cleanup fail.
+Passing tests with failed cleanup return 1; timeout returns 124; cancellation
+returns 130. Leave 70 seconds before the job's hard timeout for diagnostics and
+stop. SIGKILL and runner loss cannot run cleanup. Stop shuts down owned devices;
+it never deletes them.
+
+GitHub-hosted jobs default to $RUNNER_TEMP/stim-ci/home and
+$RUNNER_TEMP/stim-ci/build-cache, reused between steps in the job. Detection
+requires GITHUB_ACTIONS=true, RUNNER_ENVIRONMENT=github-hosted and RUNNER_TEMP.
+An explicit --home or STIM_HOME keeps the selected home and its normal cache
+configuration; --build-cache or STIM_BUILD_CACHE overrides the cache path.
+Self-hosted runners and local runs keep normal Stim configuration. Other
+exclusive disposable providers can set their job-local paths explicitly.
+CI=true alone does not change defaults, ownership or coordination. Persist only
+cache artifacts, not state, claims or device ledgers. Independent homes must
+not share a writable filesystem cache because its claims live in the home.
+
+The programmatic runner is import { runCI } from '@stim-cli/ci'. See its package
+README for result types, cancellation, cache policy, and coordination findings.`
+		},
 		"hosted-android": {
 			summary: "Android on a named approved Mac: strict placement, private Metro, status and stop",
 			body: () => `ANDROID ON A HOSTING MAC
@@ -4982,7 +5250,7 @@ policy. No flag or setting runs on this Mac.
 A named Mac is strict: refusal, unreachable, declined or failed preparation
 returns STIM_HOSTING_REFUSED without fallback. --device, a different recorded
 machine, a running local owned emulator in the slot, and --no-metro-check for
-hosted Debug refuse STIM_BAD_ARG. Run stim stop before switching placement.
+hosted Metro development apps refuse STIM_BAD_ARG. Run stim stop before switching placement.
 Unreadable android.host blocks only its slot; restore its recorded machine and
 session from the host before stopping that slot.
 
@@ -4992,7 +5260,7 @@ compatible build worker. Stim builds before reserving, records the session as
 soon as it exists, then delivers one App.apk. The emulator boots headless;
 androidEmulatorApp is ignored with a note.
 
-Debug requires the local Metro supervisor. metro.publicUrl and metro.tunnel
+React Native Debug requires the local Metro supervisor. metro.publicUrl and metro.tunnel
 are ignored with a note. A private tailnet gateway reaches the host loopback
 bridge; the host reverses the client's Metro port into that bridge on its exact
 ledger-owned serial and sets debug_http_host to localhost:<clientMetroPort>.
@@ -5002,6 +5270,14 @@ adb against the host serial on this Mac. Release variants skip Metro. Launch
 is true only with client bundle evidence or a live host release process;
 bundling requires a bundle request and unverified has no launch evidence.
 
+Native Gradle apps use process mode for every variant. The host must advertise
+hosted-android-process; older hosts refuse before admission or APK upload.
+Native runs close any previous Metro bridge, launch the signed APK and require
+a live app process for launched=true. --no-metro-check is allowed, and reload
+refuses because there is no Metro runtime. Re-run stim android after an edit.
+Native EAS/proxy targets remain unsupported. Build offload requires the complete
+android.offloadInputs declaration; see stim guide lifecycle native-android.
+
 Status adds android.host { machine, session, selected, agent, device: { name,
 systemImage, api }, state } per slot. The public name is the profile and API
 level, never the host serial or AVD name. ready, stopped and unverified are
@@ -5125,7 +5401,10 @@ there is a free concurrency.maxDevices slot (0 means unlimited), no device
 waiter ahead, normal host memory pressure, no budget shortfall,
 and 5-minute load per core below server.maxLoadPerCore. Without remote.machines,
 auto is local. An unknown local device count also stays local; boot admission
-still decides. The default without a flag or setting stays local.
+still decides. The default without a flag or setting stays local. remote.devicePoolDisabled excludes
+members from new automatic placement only; an excluded local member is never a
+fallback. Existing sessions keep their owner and named placement bypasses the pool.
+See stim guide settings for separate build/device membership controls.
 
 Otherwise Stim asks every approved remote.machines host in parallel, with a
 3-second probe timeout and this run's model/runtime or image/profile selectors.
@@ -5136,9 +5415,24 @@ Hosts rank by the build preference (flag > STIM_REMOTE_BUILD > remote.build)
 when it names a machine, then lowest load, most free memory and remote.machines order. Automatic build
 offload resolves later, after the device architecture is known.
 
-When no host admits, auto runs here and may wait in the existing FIFO device
+When no host admits and this Mac is at its concurrency.maxDevices cap (or runs
+are queued ahead), remote.easFallback (default false; EAS Simulator is billed)
+runs the device on an EAS Simulator exactly as --remote eas would: the build
+stays here, nothing starts an EAS cloud build, stop ends the session, and
+status reports it under remoteDevices. A busy Mac with a free slot never uses
+it. Before choosing it Stim checks, without starting a session, that eas-cli
+has simulator commands (and 22.2.0+ for --device-type), eas
+simulator:availability says this project's account can use it, agent-device
+is on PATH, the slot is default, no --runtime, --system-image or
+--device-profile flag is given, no EAS Simulator session of this workspace runs
+another platform or model, and a Debug run's Metro is reachable (not
+metro.tunnel off; on an Expo tunnel, run stim start --remote first). A recorded
+EAS session is not sticky: once this Mac has room, auto runs here and the
+session bills until stim stop. If any check fails, or the
+setting is off, auto runs here and may wait in the existing FIFO device
 slot queue; --no-wait and --wait 0 refuse with STIM_AT_CAPACITY. The placement
-line explains the decision and the skipped hosts. JSON progress goes to stderr.
+line explains the decision, the skipped hosts and why EAS was not used
+(machine "eas"). JSON progress goes to stderr.
 The same decision, with a reason code per host, is a src: placement record in
 stim logs (stim guide logs).
 A recorded hosted session wins over load; a live local owned slot stays here.
@@ -5180,7 +5474,7 @@ sessions.
 
 
 Stim builds or fetches before reserving, records the session immediately, then
-uploads the app on every run. Debug keeps Metro here; its supervisor owns a
+uploads the app on every run. React Native and Expo Debug keep Metro here; the supervisor owns a
 private gateway bound to this Mac's Tailscale address, pinned to the host peer
 and protected by a per-session secret. The host exposes only a loopback bridge.
 No start --remote is needed; metro.tunnel and metro.publicUrl are ignored.
@@ -5188,7 +5482,8 @@ Debug requires a running supervisor with private gateway support before reservin
 a simulator. --no-metro-check refuses with STIM_BAD_ARG for hosted Debug runs.
 If its supervisor is missing or older, run stim stop; stim start, then retry.
 Non-Debug runs skip Metro. Launch is unverified until this workspace's Metro
-provides bundle evidence, or the host proves a live release process.
+provides bundle evidence, or the host proves a live release process. Native Xcode
+apps use process mode in every configuration and require no Metro; see native-ios.
 
 A rerun on the same named Mac reattaches and delivers a new app attempt. A
 stopped or missing session is replaced; an unreachable or unknown owner refuses
@@ -5861,6 +6156,11 @@ PREDICTING THE NEXT BUILD (--plan)
   installing, or starting Metro. They take no workspace lock and write no
   Stim state, cache entry or statistic, so they run beside a build.
 
+  The selected project integration supplies the read-only plan and uses its
+  build recipe's identity and cache policy. If it has no planner, --plan
+  refuses with STIM_BAD_ARG; run the command without --plan. The refusal
+  reports no cache hit. React Native and Expo planning behaves as follows.
+
     stim ios --plan
       plan        ios 1b625d.. -> local cache hit
       expect      ~2.7s (median of 1 hit run)
@@ -5899,8 +6199,9 @@ PREDICTING THE NEXT BUILD (--plan)
   this Mac and a listed Mac would build for another architecture, placement
   says so, since that Mac's key differs. The plan only predicts the key: a
   run reads the architecture of the device it actually gets. A Mac that does
-  not answer, or ios.remote or android.remote set to eas or proxy, refuses
-  with STIM_BAD_ARG. Without --eas-profile an Android plan also
+  not answer, ios.remote or android.remote set to eas or proxy, or auto that
+  would use an EAS Simulator now (remote.easFallback), refuses with
+  STIM_BAD_ARG. Without --eas-profile an Android plan also
   refuses the experimental compiler CAS with STIM_BAD_ARG, and refuses with
   STIM_NO_DEVICE when no system image is installed.
 
@@ -5910,13 +6211,16 @@ IOS SCHEME SELECTION
   Xcode scheme, not the app's URL scheme. Combine it with --configuration
   when choosing both an app scheme and a build configuration.
 
-  Without --scheme, automatic selection is unchanged:
+  The ios.scheme setting names the scheme once for the app (guide settings);
+  --scheme overrides it per run, and both give the same keys below.
+
+  Without --scheme or ios.scheme, automatic selection is unchanged:
   Stim keeps a scheme matching the workspace/project name, or the sole non-test
   scheme. When neither identifies one, it also checks the static top-level name
   in the app directory's app.json against Xcode's listed schemes. It does not
   execute app config or choose an arbitrary scheme from an ambiguous list.
-  If selection fails, pass --scheme with an available name, or share the app
-  scheme in Xcode first. See guide errors STIM_NO_SCHEME.
+  If selection fails, pass --scheme with an available name, set ios.scheme, or
+  share the app scheme in Xcode first. See guide errors STIM_NO_SCHEME.
 
   Explicit schemes have separate artifact keys, shared-build locks, and Xcode
   build directories. Stim identifies the resulting application from Xcode's
@@ -5925,7 +6229,8 @@ IOS SCHEME SELECTION
   configured Stim cache providers use the scheme-specific key. The older Expo
   buildCacheProvider tier is skipped for explicit schemes because a provider
   may key only on the fingerprint and return another scheme's app. Omitting
-  --scheme retains the existing cache keys and provider behavior.
+  both --scheme and ios.scheme retains the existing cache keys and provider
+  behavior.
 
 AN ARTIFACT THE DEVICE ALREADY HOLDS IS NOT INSTALLED AGAIN
   Both platforms store the artifact verbatim, so its hash is its identity.
@@ -5967,7 +6272,9 @@ A RUNNING APP IS RESTARTED, LIKE XCODE'S RUN
     launch      com.example.app restarted running app (was pid 4242) (0.9s)
 
   A stop that fails refuses the launch rather than reusing the old process.
-  When the process list cannot be read, Stim launches without stopping
+  When a simulator's process list cannot be read, Stim launches with
+  \`simctl launch --terminate-running-process\`, which replaces any running
+  copy. When an emulator's cannot be read, Stim launches without stopping
   anything and verification reports what it observes. An iPhone run
   (\`ios --device\`) needs no extra step: its collector launches with
   devicectl's \`--terminate-existing\`. Remote targets launch through
@@ -6886,7 +7193,7 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   MUTATE: the cache entry stays the pristine, shareable artifact, and the
   per-run address lives only in the copy that is installed and then deleted.
 
-  A RELEASE device run builds fresh every time for now. A cached Release app
+  A React Native or Expo RELEASE device run builds fresh every time for now. A cached Release app
   carries its BUILDER's JS, and the device JS swap (which has to re-seal what
   it injects) lands with phase 6 of appandflow/stim#178, so the cache hit is
   refused rather than installed with someone else's JavaScript.
@@ -7101,8 +7408,8 @@ THE POOL: WHICH DEVICE AN ID-LESS \`--device\` PICKS
   distribution stay out of scope.
 
   \`ios --configuration <name>\` selects the Xcode configuration --
-  \`--configuration Release\` builds a SIMULATOR Release app with the JS
-  bundle embedded. It overrides the ios.configuration setting (the app-level
+  for React Native and Expo, \`--configuration Release\` builds a SIMULATOR
+  Release app with the JS bundle embedded. It overrides the ios.configuration setting (the app-level
   default); unset, the Debug flow is unchanged. A non-Debug configuration
   skips Metro ENTIRELY: no gate, no port wiring, no dev-client deep link (a
   plain \`simctl launch\`), and the payload says \`metroPort: null\` --
@@ -7191,6 +7498,19 @@ HOST MEMORY PRESSURE AND STALLED SIMULATORS
   a failed query remains unknown. Existing swap or low free RAM alone is not
   enough to diagnose pressure.
 
+  Doctor, and boot messages under warning or critical pressure, also name any
+  process whose physical footprint is abnormal, read from macOS top (it counts
+  compressed and swapped memory, which ps RSS leaves out, and reads root-owned
+  daemons). Abnormal is at least a quarter of physical memory and 8 GiB, or
+  2 GiB for fseventsd and Watchman, which are normally far smaller. A known
+  safe-to-restart process comes with its command; Stim never runs it:
+    fseventsd                      sudo killall fseventsd (launchd restarts it;
+                                   file watchers rescan once)
+    Watchman                       stim gc --delete --cache watchman
+    Gradle or Kotlin daemon        stim gc --delete --cache gradle-daemons
+  Any other process is named with its size only; ask before quitting it.
+  Doctor skips this check when STIM_HOME is set: processes are machine-global.
+
   If pressure is elevated, free host memory before retrying. Use \`stim stop\`
   only in workspaces you own and have finished using; ask before closing other
   agents' simulators or heavy apps. Never quit Device Hub or Simulator.app to
@@ -7239,7 +7559,9 @@ Pressure checks read free disk on the Stim home, projects and worker root
 volumes. On macOS the memory signal is the sysctl pressure level, with no
 signal if sysctl fails. Other platforms use os.freemem(); macOS never falls
 back to it. Memory pressure is recorded only; stopping devices, dev servers
-and helpers is not automatic.
+and helpers is not automatic. While the level is warning or critical, the
+check also names abnormally large processes (guide lifecycle simslim) in
+status's maintenance block and the maintenance log.
 
 In on mode a pass runs, cheapest to rebuild first:
   1. orphaned workspace directories whose project is gone, and registered
@@ -7620,11 +7942,11 @@ STALE STATUS CACHE ENTRIES
   if it comes back.
 
 NAMED SERVER PORTS
-  worktree remove stops TCP listeners on each named allocation and releases
-  the ports. gc reports named allocations for missing workspaces; gc --delete
-  stops their listeners and releases them. Unmounted or unresolved paths stay
-  registered. Failed stops retain their allocations for a later retry.
-  stim stop does not touch named ports. See guide ports.
+  worktree remove, gc --delete and automatic maintenance release named
+  allocations without signalling their listeners. gc reports named
+  allocations for missing workspaces; gc --delete releases them. Unmounted or
+  unresolved paths stay registered. Only ports stop stops a named listener,
+  and stim stop does not touch named ports. See guide ports.
 
 ON THE SOURCE CHECKOUT
   git cannot remove a repository's main working tree, and deleting the source
@@ -7873,7 +8195,23 @@ THE ONE CASE GC WILL NOT REAP
 
   --older-than does not apply to these kinds and is refused with
   STIM_BAD_ARG. With STIM_HOME set, gc skips them: they are machine-global.
-  \`stim doctor\` notes a watchman footprint over 2 GiB.`
+  \`stim doctor\` notes a watchman footprint over 2 GiB.
+
+  A checkout that holds its linked worktrees inside it, such as
+  .worktrees/<name>, makes a watchman root there crawl every worktree's files,
+  node_modules and build output. \`stim doctor\` reports each such checkout
+  whose .watchmanconfig ignore_dirs does not exclude them, as
+  ${WATCHMAN_NESTED_WORKTREES}, and says when watchman watches it now.
+  \`stim doctor --fix\` merges the worktrees' shared parent (.worktrees) when
+  git tracks nothing in it, otherwise each worktree path, into that
+  checkout's .watchmanconfig and keeps every other key; it refuses a file
+  that is not a JSON object or whose ignore_dirs is not an array. Watchman
+  matches entries literally: \`.worktrees/\` or \`./.worktrees\` ignores
+  nothing. Commit the file. Watchman reads ignore_dirs only from a root's
+  .watchmanconfig, never from a global config, and only when it adds the
+  root, so an existing root needs \`watchman watch-del <root>\` before the
+  ignore applies. Doctor never runs watch-del or shutdown-server; a watch-del
+  plus a watchman restart frees the memory now.`
 		},
 		disk: {
 			summary: "disk usage, workspace build outputs, logs and device recordings, AVD and build-log sizes, the data partition, trimming the shared caches",
@@ -8120,6 +8458,15 @@ KEYS STIM READS
                         The \`--runtime\` flag overrides this per invocation,
                         and an uninstalled version refuses the same way,
                         naming the layer the value came from
+  ios.scheme            e.g. "RNTester" -- the shared Xcode scheme to build
+                        when the workspace lists several and none matches
+                        its name, which otherwise refuses with
+                        STIM_NO_SCHEME. The \`--scheme\` flag overrides it
+                        per invocation; an \`--eas-profile\` build reads only
+                        the flag. Part of the cache key, like the flag, so
+                        it also skips the older Expo buildCacheProvider tier,
+                        which may key only on the fingerprint. Workspace or
+                        committed scope.
   ios.configuration     e.g. "Release" -- the Xcode configuration to build
                         (simulator only). Committing
                         { "ios": { "configuration": "Release" } } makes every
@@ -8130,7 +8477,21 @@ KEYS STIM READS
   ios.remote            "proxy", "eas", or a named approved Mac from
                         remote.machines, with the same meaning as --remote.
                         "auto" places on an approved Mac when this Mac is full or
-                        busy. Unset runs here. See lifecycle hosted-ios.
+                        busy. Unset runs here; "local" runs here even when a
+                        lower layer says otherwise. See lifecycle hosted-ios.
+  ios.projectPath       directory under the app holding a bare React Native
+                        app's Xcode project and Podfile; default "ios". "."
+                        is the app directory itself (RNTester's layout).
+                        Detection, pod install, xcodebuild, the bundle id,
+                        doctor, worktree warm and remove, and remote builds
+                        all use it. A subdirectory is fingerprinted the way
+                        ios/ is; "." hashes every top-level entry except
+                        node_modules, Pods, build, android, .stim.json and
+                        anything git ignores, so a JS edit misses the build
+                        cache instead of risking a stale build. Workspace or committed scope. ios refuses
+                        with STIM_BAD_ARG a path that escapes the app or
+                        holds no .xcworkspace or .xcodeproj, and any value
+                        on an Expo app, whose prebuild writes ios/.
   ios.simslimProfile    a SimSlim JSON profile under the app directory,
                         at most 64 KiB. Install the
                         external tool once with
@@ -8241,6 +8602,26 @@ ${ANDROID_AVD_CONFIG_HELP.map((line) => `                          ${line}`).joi
                         and hw.audioOutput for that headless launch. With
                         androidEmulatorApp "stim-desktop" on macOS, -gpu host
                         overrides hw.gpu.mode the same way.
+  android.gradleRoot    directory holding gradlew and settings.gradle(.kts),
+                        relative to the app; default "android". It may sit
+                        outside the app but not outside the repository:
+                        RNTester in the React Native monorepo uses "../..".
+  android.module        the app's Gradle project path; default ":app", e.g.
+                        ":packages:rn-tester:android:app". Its directory is
+                        Gradle's default mapping from the root and must hold
+                        a build.gradle(.kts). With either set, Gradle runs
+                        from the root with qualified tasks such as
+                        <module>:assembleDebug; both values join the cache
+                        key and the remote build job, and the root's
+                        settings, build script, gradle.properties and
+                        gradle/ are fingerprinted. Native sources Gradle
+                        builds from elsewhere in the repository are not:
+                        list them in fingerprint.config.js extraSources.
+                        android refuses with STIM_BAD_ARG a root outside the
+                        repository or without settings.gradle, a module
+                        without a build script, and either value on an Expo
+                        app, whose prebuild writes android/. Workspace or
+                        committed scope.
   android.variant       e.g. "productionDebug" -- the gradle variant to
                         assemble and install on a project with product
                         flavors. A repo like tlon-mobile with
@@ -8256,24 +8637,55 @@ ${ANDROID_AVD_CONFIG_HELP.map((line) => `                          ${line}`).joi
                         build: embedded JS, no Metro, cache keyed on the
                         variant, and an APK re-pack on cache hits. See
                         \`guide lifecycle release\`.
+  android.offloadInputs a native Gradle build-worker declaration:
+                        {"complete":true,"ignored":[],"outputs":["build","app/build"]}.
+                        complete confirms Git-visible source plus the exact
+                        repository-relative ignored files suffice for this
+                        build. outputs names generated directories reported
+                        by AGP; recorded outputs can survive worker sync.
+                        Omitted optional inputs can change build results.
+                        Stim artifact caching remains unavailable. See
+                        \`stim guide lifecycle native-android\` for input,
+                        privacy and worker requirements.
   android.keystore      the keystore a RE-PACKED release APK is signed with,
                         absolute or relative to the project root. Unset means
                         android/app/debug.keystore, which every RN and Expo
                         android project carries -- the right default, because
                         what this signs is a local emulator install and never
                         anything distributed. Set it only when the release
-                        variant must be signed with the repo's own key.
+                        variant must be signed with the repo's own key. A
+                        value in the committed .stim.json must resolve
+                        inside the repository (symlinks included); an
+                        absolute path outside it needs --scope workspace
+                        or repo.
   android.keystorePassword
                         the password for it. apksigner's SCHEMED form is
                         passed through unchanged (\`env:MY_KS_PASS\`,
                         \`file:/keys/pw.txt\`, \`stdin\`), which is how a
                         committed .stim.json avoids carrying a secret; a
-                        bare string is used as the literal password. Unset
-                        means the debug keystore's fixed "android".
+                        bare string (or \`pass:<password>\`) is the literal
+                        password, handed to apksigner through its
+                        environment, never its command line. Unset means
+                        the debug keystore's fixed "android".
   android.remote        "proxy", "eas", or a named approved Mac in
                         remote.machines; "auto" places on an approved Mac when
-                        this Mac is full or busy. Unset runs here.
+                        this Mac is full or busy. Unset runs here; "local"
+                        runs here even when a lower layer says otherwise.
                         See lifecycle hosted-android.
+  remote.easFallback    true lets "auto" (ios.remote, android.remote or
+                        --remote auto) run the simulator or emulator on a
+                        billed EAS Simulator when this Mac is at its
+                        concurrency.maxDevices cap (or has runs queued) and no
+                        remote.machines Mac takes the run, instead of waiting
+                        or refusing with STIM_AT_CAPACITY. Default false. A
+                        busy Mac with a free slot never uses it. Stim checks
+                        first that the run could use --remote eas (eas-cli
+                        with simulator commands, eas simulator:availability,
+                        agent-device, the default slot, a reachable Metro);
+                        otherwise it waits or refuses as before. Machine or
+                        project scope; a committed value opts in everyone who
+                        runs the app. Only the user enables it. See lifecycle
+                        hosted-ios.
   metro.tunnel          selects how a remote device reaches this workspace's
                         Metro after remote intent exists. Plain \`start\` stays
                         local. For Expo and bare React Native, "auto" (default)
@@ -8288,6 +8700,21 @@ ${ANDROID_AVD_CONFIG_HELP.map((line) => `                          ${line}`).joi
                         foreground serve process, never Funnel; "auto" never
                         selects it. The device must share the tailnet. See
                         \`guide metro\`. Any other value is refused as invalid.
+  metro.command         argv array that starts this app's dev server, for an
+                        app whose Metro only runs through its own command,
+                        e.g. ["node", "../react-native/cli.js", "start",
+                        "--port", "{port}"]. No shell; it runs from the app
+                        directory, and {port} becomes the reserved Metro port,
+                        which the command must pass. It replaces bare-inproc
+                        and expo-child with command-child (see \`guide
+                        metro\`). Workspace or committed scope.
+                        Metro must keep running from inside the app, which
+                        is how Stim proves it is this app's. Without Stim's
+                        Metro reporter, launches stay UNVERIFIED. start
+                        refuses with STIM_BAD_ARG a value that is not such an
+                        array or has no {port}, --reset-cache (put the
+                        command's own reset flag in metro.command instead),
+                        and any use on Windows.
   metro.ngrokUrl        the stable managed ngrok URL. It requires metro.tunnel
                         "ngrok" and passes --url to ngrok http. Stim owns
                         this process.
@@ -8522,8 +8949,9 @@ To show the booted simulator in Stim Desktop and open no simulator window:
 
   { "iosSimulatorApp": "stim-desktop" }
 
-Stim Desktop selects the workspace that owns the simulator and focuses that
-device. It only displays the simulator; it never boots or shuts it down.
+Stim Desktop keeps the current page and shows a launch card. Clicking Show
+opens the workspace that owns the simulator and focuses that device.
+It only displays the simulator; it never boots or shuts it down.
 When Stim Desktop is not running, Stim starts it without the command's
 \`STIM_HOME\`, so it reads the same Stim home as when you open it yourself.
 It shows only devices from that home: under another \`STIM_HOME\`, pick
@@ -8552,7 +8980,8 @@ headlessly and show it in Stim Desktop:
   { "androidEmulatorApp": "stim-desktop" }
 
 Stim then starts the emulator with \`-no-window -gpu host\` and opens
-\`stim-desktop://open?serial=<serial>\` in the background. Stim Desktop reads
+\`stim-desktop://open?serial=<serial>\` in the background. Stim Desktop shows a
+launch card and opens the emulator only when Show is clicked. It reads
 frames and sends input over the emulator's gRPC endpoint. The setting applies
 only when Stim boots the emulator: one that is already running keeps its
 current display until it next boots, and physical devices are unaffected.
@@ -8635,6 +9064,32 @@ simulator sessions on, by MagicDNS name with an optional serve port (default
   stim settings set remote.machines '["janics-mac-mini"]'
   stim doctor --fix
 
+Automatic membership is separate from approval. In Desktop Settings > Remote Macs,
+use Builds enabled and Simulators enabled for this Mac or a configured remote.
+The equivalent machine settings list the excluded members; both default to []:
+
+  stim settings set remote.buildPoolDisabled '["local"]'
+  stim settings set remote.devicePoolDisabled '["janics-mac-mini"]'
+  stim settings unset remote.buildPoolDisabled
+
+Use local for this Mac and exact remote.machines entries for remotes, including
+case and port. Names are not trimmed; unmatched entries exclude nothing. Copy the
+configured name or use Desktop's switches. Each pool
+must retain local or at least one configured remote already approved for that role.
+Offline approved members count as configured members, but placement still requires
+an available compatible host. Settings refuses removing the last member, including
+removing it from remote.machines. Disabling does not unpair a machine or stop a run.
+
+These settings apply only to new automatic work requested by this Mac. They do not
+change which work other requesters send to a host. Named placement and --remote-build
+local bypass membership; the default device placement without --remote auto remains
+local. Existing local and hosted device sessions keep their owner. Cache hits remain
+usable without compiling. If local is excluded, automatic placement cannot fall back
+to a local compile or boot; unavailable hosts and unsupported offloads refuse. Excluding
+local alone does not trigger billed EAS fallback; an existing explicit EAS opt-in still
+requires the physical device cap or queue condition. Restore membership before retrying or choose
+an explicit placement. Build and simulator memberships are independent.
+
 A remote Mac is used for a capability only after it grants that approval. Build
 and device-host approvals are separate: a Mac in the list that never granted
 one is not an error, it is not used for that capability, and doctor reports
@@ -8726,7 +9181,7 @@ value is unset. Trimmed auto/local are case-insensitive. Machine names match
 configured names case-insensitively, with port 7443 when omitted; reports use
 the configured entry.
 
-  auto   follows remote.buildMode and keeps its local fallback behavior
+  auto   follows remote.buildMode, considering only enabled automatic pool members
   local  builds only on this Mac for this invocation
   name   requires a matching entry in remote.machines, already paired and
          approved for builds; ignores remote.buildMode and this Mac's load/slot gating
@@ -8765,7 +9220,7 @@ emulator debug build or a stim macos SwiftPM Debug build compiles:
          Mac's. A Mac too old to report its load counts only while every
          slot here is busy.
   force  on a remote Mac whenever one accepts it
-  off    always here
+  off    here when local remains enabled in the automatic build pool
 
 Load per core is the 5-minute load average divided by the CPU count; a Mac's
 native builds are its Stim runs in prebuild, pods or compile on that Mac, not
@@ -8793,7 +9248,7 @@ iPhone simulator on the target runtime. Its project-selected CocoaPods must matc
 the app's Gemfile.lock pins CocoaPods: both Macs then run that version through
 bundler, so the machine needs only Bundler on its stim-server PATH and
 installs the pinned gems itself on the first build. The comparison selects
-the app's .ruby-version when installed, with pod install's UTF-8 locale defaults.
+the app's .ruby-version when installed, and otherwise the GEM_HOME, GEM_PATH and Ruby-related PATH entries of the Mac's login shell (read once with $SHELL -lic), unless the caller already sets GEM_HOME, with pod install's UTF-8 locale defaults. pod install, including the Bundler run, uses the same environment.
 For Android its JDK major
 version must match, and its Android SDK must hold the NDK, build-tools and
 compile platform that the project's React Native version names in
@@ -9225,7 +9680,7 @@ the same as for any web project: start the dev server, then run stim web.
   stim logs --errors
   stim reload web
   stim stop               # closes Chrome; stim ports stop web stops Vite
-  stim worktree remove    # in a linked worktree: Chrome, Vite and profile
+  stim worktree remove    # in a linked worktree: Chrome and profile, not Vite
 
 The repo layer is shared by every worktree of the repository, so a new
 worktree skips the two settings lines; the certificate and scheme remedies
@@ -9416,18 +9871,39 @@ executables, including Stim Desktop's sim-fold helper, are not built.
 
   stim macos              # fixed SwiftPM Debug build, then launch
   stim macos --json       # one launch record; progress goes to stderr
+  stim macos --plan --json # validate the next build without running it
   stim status --json      # environments[].macos and build state
   stim logs --source build
   stim logs --errors
   stim stop               # stop this workspace's owned app and supervisor
 
-Each invocation stops its previous owned app, rebuilds and launches. SwiftPM
+Each invocation validates the project settings, development plist and resource
+entries before stopping its previous owned app, rebuilding and launching. SwiftPM
 keeps incremental outputs in the workspace's runtime directory under STIM_HOME.
+Every process running an app bundle from that directory is the workspace's
+owned app, including copies opened through LaunchServices (open, agent-device
+open). stim macos, stim stop, stim worktree remove and stim gc --delete stop all
+of them: SIGTERM, up to 5 s, then SIGKILL, and success only once each has
+exited. When an app cannot be verified or does not exit, stop reports
+STIM_MACOS_OWNER_UNVERIFIED or a failure, and removal keeps the workspace.
 Local stim macos starts the app in the background without activating it or
 changing focus: it sets STIM_BACKGROUND_LAUNCH=1 in the app's environment, which
-Stim Desktop honors. An app that activates itself at launch still takes focus.
+Stim Desktop honors, including for reopen events from open -g. An app that
+activates itself at launch or on reopen still takes focus.
 Hosted launches (macos --remote) do not set it.
-macOS artifacts are not cached. This prototype has no --plan, --slot, or reload command.
+macOS artifacts are not cached. This prototype has no --slot or reload command.
+--plan validates the Swift Package directory, macos settings, development plist
+and declared resources without building, signing, staging, stopping or launching
+an app, writing workspace state or claiming a build slot. It does not execute
+Package.swift, so it cannot validate the executable product or package dependencies.
+--remote-build is respected, including named-machine setup refusals; no worker
+is contacted and live worker availability is unknown. --remote is launch-only
+and refuses with --plan. The JSON plan has platform "macos", product and
+buildMachine; fingerprint, cacheKey, provider, prebuild, outcome and expectedMs
+are null, cacheHit and cacheSkipped are false, and basis is 0. SwiftPM decides
+incremental compile work when a build runs; the plan predicts no cache outcome
+or duration. Desktop checks automatically while build details are visible,
+reusing a completed build or check for 60 seconds and skipping running builds.
 A failed build records its error and compiler output without launching an app.
 While it runs, stim status --json reports it as environments[].build with
 platform "macos": phase prepare, compile, install, then launch, and during
@@ -9453,7 +9929,10 @@ refuse before stopping the app or changing its build record. See stim guide erro
 
 With remote.build auto, remote.buildMode places these SwiftPM Debug builds:
 auto builds here while this Mac has capacity, force uses an approved build
-machine when one accepts, and off always builds here. Configure remote.machines
+machine when one accepts, and off builds here when local remains in the automatic
+build pool. remote.buildPoolDisabled excludes members from automatic placement,
+including its local fallback. Explicit local or named placement bypasses membership.
+Configure remote.machines
 and approve build access as described in stim guide settings. The worker needs
 matching Stim, CPU architecture, Xcode and macOS SDK, plus network access to
 fetch package dependencies the first time. It keeps SwiftPM dependencies in a
@@ -9771,290 +10250,178 @@ this workspace's app. Do not change permissions or use custom build scripts."
 };
 //#endregion
 //#region src/guide/tutorial-data.ts
-const TUTORIAL_PINS = {
-	createExpoApp: "5.0.0",
-	template: "expo-template-blank@58.0.15"
-};
-const TUTORIAL_FILES = {
-	"App.js": `import { useEffect, useState } from 'react';
-import { Pressable, StyleSheet, Text, View } from 'react-native';
-import { StatusBar } from 'expo-status-bar';
-import { TITLE_COLOR } from './theme';
-
-const TAG = '[stim:tutorial]';
-
-function Button({ label, onPress }) {
-  return (
-    <Pressable accessibilityRole="button" onPress={onPress} style={styles.button}>
-      <Text style={styles.buttonText}>{label}</Text>
-    </Pressable>
-  );
-}
-
-export default function App() {
-  const [note, setNote] = useState('');
-
-  useEffect(() => {
-    console.log(\`\${TAG} title color=\${TITLE_COLOR}\`);
-  }, [TITLE_COLOR]);
-
-  const logError = () => {
-    console.error(\`\${TAG} error-button test error\`);
-    setNote('Logged an error.');
-  };
-
-  const crash = () => {
-    setTimeout(() => {
-      throw new Error(\`\${TAG} crash-button uncaught test error\`);
-    }, 0);
-  };
-
-  const slowRequest = async () => {
-    const started = Date.now();
-    setNote('Waiting 3 seconds...');
-    await new Promise((resolve) => setTimeout(resolve, 3000));
-    const elapsed = Date.now() - started;
-    console.warn(\`\${TAG} slow-request \${elapsed}ms\`);
-    setNote(\`Slow request took \${elapsed}ms.\`);
-  };
-
-  return (
-    <View style={styles.container}>
-      <Text style={[styles.title, { color: TITLE_COLOR }]}>Stim Tutorial</Text>
-      <Text style={styles.body}>Tap a button, then look at Stim Desktop &gt; Logs.</Text>
-      <Button label="Log an error" onPress={logError} />
-      <Button label="Crash me" onPress={crash} />
-      <Button label="Slow request" onPress={slowRequest} />
-      <Text style={styles.note}>{note}</Text>
-      <StatusBar style="auto" />
-    </View>
-  );
-}
-
-const styles = StyleSheet.create({
-  container: { flex: 1, backgroundColor: '#fff', alignItems: 'center', justifyContent: 'center', padding: 24 },
-  title: { fontSize: 32, fontWeight: '700', marginBottom: 8 },
-  body: { fontSize: 16, color: '#4b5563', textAlign: 'center', marginBottom: 24 },
-  button: { backgroundColor: '#111827', borderRadius: 10, paddingVertical: 14, paddingHorizontal: 28, marginBottom: 12 },
-  buttonText: { color: '#fff', fontSize: 17, fontWeight: '600' },
-  note: { marginTop: 12, fontSize: 15, color: '#374151' },
-});
-`,
-	"theme.js": `export const TITLE_COLOR = '#1f2937';
-`,
-	"app.json": `{
-  "expo": {
-    "name": "Stim Tutorial",
-    "slug": "stim-tutorial",
-    "version": "1.0.0",
-    "orientation": "portrait",
-    "icon": "./assets/icon.png",
-    "userInterfaceStyle": "light",
-    "ios": {
-      "supportsTablet": true,
-      "bundleIdentifier": "dev.stim.tutorial"
-    },
-    "android": {
-      "adaptiveIcon": {
-        "backgroundColor": "#E6F4FE",
-        "foregroundImage": "./assets/android-icon-foreground.png",
-        "backgroundImage": "./assets/android-icon-background.png",
-        "monochromeImage": "./assets/android-icon-monochrome.png"
-      },
-      "package": "dev.stim.tutorial"
-    },
-    "web": {
-      "favicon": "./assets/favicon.png"
-    },
-    "extra": {
-      "stimTutorial": 1
-    }
-  }
-}
-`,
-	".gitignore": `/ios
-/android
-/tutorial*.ad
-/tutorial*.png
-`
-};
-const TUTORIAL_PROMPTS = {
-	begin: "Run the Stim tutorial.",
-	rebuild: "Continue the Stim tutorial: rebuild",
-	agent: "Continue the Stim tutorial: agent",
-	refresh: "Continue the Stim tutorial: refresh",
-	machine: "Continue the Stim tutorial: machine",
-	finish: "Continue the Stim tutorial: finish"
-};
+const TUTORIAL_REPO = "appandflow/stim-tutorial";
+const TUTORIAL_BUNDLE_ID = "dev.stim.tutorial";
 const TUTORIAL_RESTART_PROMPT = "Restart the Stim tutorial.";
+/**
+* The requests Stim Desktop offers to copy, written the way a developer would ask. {base}, {tour} and {worktrees}
+* are filled in by Desktop. A step with a section names the guide section that holds its safety rules.
+*/
+const TUTORIAL_ASKS = {
+	begin: `Clone ${TUTORIAL_REPO} into {base} and follow stim guide tutorial run.`,
+	build: "Make the title purple in the Stim tutorial app and check it on the simulator.",
+	agent: "Open the app on the iOS simulator, take a screenshot and confirm the title color.",
+	finish: "I'm done with these experiments in {base} and don't need the changes. Stop the apps and remove the worktrees {worktrees}, and keep the clone. Follow stim guide tutorial finish.",
+	delete: "Remove the Stim tutorial: remove its worktrees and the clone at {base} with stim worktree remove, then delete {base}. Follow stim guide tutorial delete.",
+	share: `Open a pull request to ${TUTORIAL_REPO} with my title color change, with before and after screenshots from the simulator. See stim guide tutorial share.`,
+	retry: "The first iOS build of the tutorial app in {tour} failed. Find out why and run it on iOS again."
+};
 const TUTORIAL_STEPS = [
 	{
 		id: "begin",
-		title: "Create the Tutorial",
+		title: "Get the Test App",
 		who: "agent",
 		optional: false,
-		prompt: TUTORIAL_PROMPTS.begin,
+		ask: TUTORIAL_ASKS.begin,
 		section: "run",
-		manual: [
-			"base=\"{base}\"",
-			"mkdir -p \"${base%/*}\"",
-			"if [ ! -e \"$base\" ]; then",
-			"cd \"${base%/*}\"",
-			"if git -C \"${base%/*}\" rev-parse --is-inside-work-tree >/dev/null 2>&1; then echo \"Stop: inside another repository. Ask for another folder; never git add in the user repository.\"; exit 1; fi",
-			`npx --yes create-expo-app@${TUTORIAL_PINS.createExpoApp} stim-tutorial --template ${TUTORIAL_PINS.template} --no-install --no-agents-md --yes`,
-			"cd \"$base\"",
-			"stim guide tutorial app",
-			...Object.entries(TUTORIAL_FILES).flatMap(([name, content]) => [`cat ${name === ".gitignore" ? ">>" : ">"} ${name} <<'STIM_TUTORIAL_EOF'`].concat(content.trimEnd().split("\n"), "STIM_TUTORIAL_EOF")),
-			"npm install --prefer-offline",
-			"npm pkg set scripts.ios=\"expo run:ios\" scripts.android=\"expo run:android\"",
-			"git init",
-			"git add -A",
-			"git -c user.name=Stim -c user.email=stim@localhost -c commit.gpgsign=false commit -m \"Stim tutorial\"",
-			"else",
-			"cd \"$base\"",
-			`node -e 'const fs = require("node:fs"); const app = fs.existsSync("app.json") ? JSON.parse(fs.readFileSync("app.json", "utf8")) : null; if (app?.expo?.extra?.stimTutorial !== ${JSON.parse(TUTORIAL_FILES["app.json"]).expo.extra.stimTutorial}) { console.error("Stop: existing non-tutorial folder or another version. Ask for another folder; never overwrite or delete it."); process.exit(1); }'`,
-			`git rev-parse --show-toplevel | node -e 'const fs = require("node:fs"); const root = fs.readFileSync(0, "utf8").trim(); if (fs.realpathSync(root) !== fs.realpathSync(process.cwd())) { console.error("Stop: inside another repository. Ask for another folder; never git add in the user repository."); process.exit(1); }'`,
-			"fi"
-		]
+		commands: []
 	},
 	{
-		id: "sidebar",
-		title: "Workspace in Sidebar",
+		id: "build",
+		title: "Make a Change",
 		who: "you",
 		optional: false,
-		prompt: null,
+		ask: TUTORIAL_ASKS.build,
 		section: null,
-		manual: []
+		commands: []
 	},
 	{
-		id: "build",
-		title: "First iOS Build",
+		id: "parallel",
+		title: "Change It Again in Parallel",
 		who: "you",
 		optional: false,
-		prompt: null,
+		ask: null,
 		section: null,
-		manual: [
-			"cd \"{base}\"",
-			"git worktree add -B stim-tutorial/tour \"{tour}\" HEAD",
-			"cd \"{tour}\"",
-			"stim worktree warm",
-			"stim guide agent",
-			"stim doctor --platform ios",
-			"stim start",
-			"stim ios"
-		]
-	},
-	{
-		id: "rebuild",
-		title: "Rebuild from Cache",
-		who: "agent",
-		optional: false,
-		prompt: TUTORIAL_PROMPTS.rebuild,
-		section: "rebuild",
-		manual: [
-			"cd \"{tour}\"",
-			"stim ios",
-			"stim status --json"
-		]
+		commands: []
 	},
 	{
 		id: "device",
 		title: "Live View and Control",
 		who: "you",
-		optional: false,
-		prompt: null,
-		section: null,
-		manual: ["stim status"]
-	},
-	{
-		id: "logs",
-		title: "App Logs",
-		who: "you",
-		optional: false,
-		prompt: null,
+		optional: true,
+		ask: null,
 		section: null,
-		manual: ["stim logs --errors", "stim logs --grep '\\[stim:tutorial\\]'"]
+		commands: ["stim status"]
 	},
 	{
 		id: "agent",
 		title: "Agent Actions and Replay",
 		who: "agent",
-		optional: false,
-		prompt: TUTORIAL_PROMPTS.agent,
-		section: "agent",
-		manual: [
+		optional: true,
+		ask: TUTORIAL_ASKS.agent,
+		section: null,
+		commands: [
 			"cd \"{tour}\"",
 			"export AGENT_DEVICE_STATE_DIR=\"{stateDir}\"",
-			"stim status --json",
-			"read -r iosUdid",
-			"agent-device open dev.stim.tutorial --platform ios --udid \"$iosUdid\" --save-script=tutorial.ad",
-			"agent-device react-native dismiss-overlay || true",
-			`agent-device press 'label="Log an error"' --settle`,
+			`agent-device open ${TUTORIAL_BUNDLE_ID} --platform ios --udid {udid}`,
 			"agent-device screenshot tutorial.png",
 			"agent-device close",
-			"grep -v -e 'target-v1' -e 'dismiss-overlay' tutorial.ad > tutorial-replay.ad",
-			"agent-device replay tutorial-replay.ad --platform ios --udid \"$iosUdid\"",
 			"stim logs --source agent --tail 10"
 		]
 	},
 	{
-		id: "refresh",
-		title: "Fast Refresh",
-		who: "agent",
-		optional: false,
-		prompt: TUTORIAL_PROMPTS.refresh,
-		section: "refresh",
-		manual: [
-			"cd \"{tour}\"",
-			"cat > theme.js <<'STIM_TUTORIAL_EOF'",
-			"export const TITLE_COLOR = '#7c3aed';",
-			"STIM_TUTORIAL_EOF",
-			"sleep 6",
-			"stim logs --errors",
-			"stim logs --grep 'title color'"
-		]
+		id: "logs",
+		title: "App Logs",
+		who: "you",
+		optional: true,
+		ask: null,
+		section: null,
+		commands: ["stim logs --errors", "stim logs --grep stim:tutorial"]
 	},
 	{
 		id: "phone",
 		title: "Watch on Your Phone",
 		who: "you",
 		optional: true,
-		prompt: null,
+		ask: null,
 		section: null,
-		manual: []
+		commands: []
 	},
 	{
-		id: "machine",
-		title: "Build on Another Mac",
-		who: "both",
+		id: "share",
+		title: "Share Your Finish",
+		who: "you",
 		optional: true,
-		prompt: TUTORIAL_PROMPTS.machine,
-		section: "machine",
-		manual: ["cd \"{tour}\"", "stim ios --remote-build \"{machine}\" --no-build-cache"]
+		ask: TUTORIAL_ASKS.share,
+		section: "share",
+		commands: [
+			"cd \"{tour}\"",
+			"git commit -am \"<one-line summary>\"",
+			"mkdir -p .expo/screenshots",
+			"git checkout origin/main -- theme.js",
+			"xcrun simctl io {udid} screenshot .expo/screenshots/before.png",
+			"git checkout HEAD -- theme.js",
+			"xcrun simctl io {udid} screenshot .expo/screenshots/after.png",
+			"cp .github/pull_request_template.md .expo/screenshots/body.md",
+			`gh repo fork ${TUTORIAL_REPO} --remote --remote-name fork`,
+			"git push -u fork HEAD",
+			`gh pr create --repo ${TUTORIAL_REPO} --title "<one-line summary>" --body-file .expo/screenshots/body.md --attach ".expo/screenshots/before.png#Before" --attach ".expo/screenshots/after.png#After"`
+		]
 	},
 	{
 		id: "finish",
 		title: "Finish and Archive",
 		who: "agent",
 		optional: false,
-		prompt: TUTORIAL_PROMPTS.finish,
+		ask: TUTORIAL_ASKS.finish,
 		section: "finish",
-		manual: [
-			"git -C \"{tour}\" checkout -- theme.js",
+		commands: [
 			"cd \"{tour}\"",
 			"stim stop",
+			"cd \"{second}\"",
+			"stim stop",
 			"cd \"{base}\"",
-			"stim worktree remove \"{tour}\""
+			"stim worktree remove \"{tour}\"",
+			"stim worktree remove \"{second}\""
+		]
+	},
+	{
+		id: "delete",
+		title: "Delete the Test App",
+		who: "agent",
+		optional: true,
+		ask: TUTORIAL_ASKS.delete,
+		section: "delete",
+		commands: [
+			"cd \"{base}\"",
+			"grep stimTutorial app.json",
+			"git worktree list",
+			"stim stop",
+			"stim worktree remove \"{base}\"",
+			"cd ..",
+			"rm -rf \"{base}\""
 		]
 	}
 ];
 //#endregion
 //#region src/guide/tutorial.ts
-const paths = `Use {base} = ~/stim-tutorial and {tour} = ~/stim-tutorial-tour unless the
-user named another parent folder. Expand ~ to the absolute home path when
-substituting inside quotes. Keep the tutorial outside the user's project.`;
+const paths = `Use {base} = ~/stim-tutorial unless the user named another folder. Expand ~
+to the absolute home path when substituting inside quotes. Keep the tutorial
+outside the user's own projects.`;
+const local = `The tutorial runs on this Mac. Every time you run the tutorial app on iOS
+from a worktree of {base}, use stim ios --remote local --remote-build local,
+even when the user's settings would place the device or the build on another
+Mac. Only an explicit request to build on another Mac changes the build, with
+stim ios --remote local --remote-build "<machine>"; the device stays here.`;
+const screenshots = `Before and after screenshots, for a pull request: in each change's worktree,
+run the app on iOS before you edit anything, open it with agent-device and save
+the screen, then make the change and, once Fast Refresh applies it, save the
+same screen on the same device:
+
+  mkdir -p .expo/screenshots
+  export AGENT_DEVICE_STATE_DIR="<agentDevice.stateDir from stim status --json>"
+  agent-device open ${TUTORIAL_BUNDLE_ID} --platform ios --udid <ios.udid>
+  agent-device screenshot .expo/screenshots/before.png
+  (make the change)
+  agent-device screenshot .expo/screenshots/after.png
+
+Without agent-device, use xcrun simctl io <ios.udid> screenshot
+.expo/screenshots/before.png, using that worktree's udid from stim status --json,
+never booted. Take both with the same tool so they match in size. .expo/ is
+ignored and outside the native fingerprint, so the files are never committed,
+never change the build, and never block stim worktree remove. Keep each PNG under 1 MB.`;
 function commands(id) {
-	return TUTORIAL_STEPS.find((step) => step.id === id).manual.join("\n");
+	return TUTORIAL_STEPS.find((step) => step.id === id).commands.join("\n");
 }
 //#endregion
 //#region src/guide/index.ts
@@ -10072,260 +10439,217 @@ const TOPICS = {
 	web: web_default,
 	macos: macos_default,
 	tutorial: {
-		summary: "An iOS tutorial: isolated worktree, builds, devices, logs, agent actions, and cleanup",
+		summary: "A cloned test app: a first build, a second change in parallel with a cache hit, and cleanup",
 		sectionHint: "run",
 		preamble: () => `STIM TUTORIAL
 
-Create a small Expo app in its own repository and tour worktree. Follow the
-normal Stim flow on iOS, then inspect builds, cache reuse, device control,
-logs, agent actions, Fast Refresh, and cleanup.
+The tutorial clones ${TUTORIAL_REPO}, a tiny Expo app, into {base}; the clone is
+never run, and only the optional delete step removes it. The user then asks for a visual change, and for another
+change while the first builds. Each change runs in its own linked worktree of
+{base}, so each has its own simulator and Metro port, and the second worktree's
+first iOS build reuses the first one's native build. Only the clone, the
+optional share and the cleanup need this guide: the changes are ordinary
+requests, so follow stim guide agent for them, and check each change on the
+device.
 
-Run one section per user request. Then end the turn, say what to look at in
-Stim Desktop, and give the next prompt. Pause never means stim stop.
-"${TUTORIAL_PROMPTS.begin}" means stim guide tutorial run.
-"Continue the Stim tutorial: <section>" means stim guide tutorial <section>.
-"${TUTORIAL_RESTART_PROMPT}" means stim guide tutorial restart.
+${local}
 
-Without Stim Desktop, use the simulator, stim status for the workspace and
-device, stim logs --errors for errors, and stim stats for build performance.
-Follow stim guide agent for doctor, errors, consent, and cleanup. Never pair
-phones, approve machines, or grant access on the user's behalf.
+"Follow stim guide tutorial run" means stim guide tutorial run.
+"Follow stim guide tutorial finish" means stim guide tutorial finish.
+"Follow stim guide tutorial delete" means stim guide tutorial delete.
+"${TUTORIAL_RESTART_PROMPT}" means stim guide tutorial restart.
 
 ${paths}
 
-Start with stim guide tutorial run. For commands to type yourself, read
-stim guide tutorial manual. The first run needs network access unless the
-required npm and native dependencies are already cached.`,
+Never pair phones, approve machines, or grant access on the user's behalf.
+For commands to type yourself, read stim guide tutorial manual.`,
 		sections: {
 			run: {
-				summary: "Create or reuse the app, warm a tour worktree, and build on iOS",
+				summary: "Clone the test app into a fresh folder and install its dependencies",
 				body: () => `RUN THE TUTORIAL
 
 ${paths}
 
-Folder safety: create the base folder only if absent. Reuse an existing
-folder only if app.json's expo.extra.stimTutorial equals this guide's version,
-${JSON.parse(TUTORIAL_FILES["app.json"]).expo.extra.stimTutorial}; skip creation and file writes when reusing it. For an existing non-tutorial
-folder or another tutorial version, stop and ask the user for another folder.
-Never overwrite or delete it.
-
-For a new app, first check the selected parent folder: create it if absent,
-then run git -C <parent> rev-parse --is-inside-work-tree. If it succeeds, the
-folder is inside another repository: stop and ask the user for another folder.
-Never git add in the user's repo. Then, from the parent folder, run:
-
-  npx --yes create-expo-app@${TUTORIAL_PINS.createExpoApp} stim-tutorial --template ${TUTORIAL_PINS.template} --no-install --no-agents-md --yes
-
-Enter the base folder. Run stim guide tutorial app, write its three app files
-verbatim, and append its .gitignore lines. Then run:
-
-  npm install --prefer-offline
-  npm pkg set scripts.ios="expo run:ios" scripts.android="expo run:android"
-  git init
-  git add -A
-  git -c user.name=Stim -c user.email=stim@localhost -c commit.gpgsign=false commit -m "Stim tutorial"
-
-On reuse, run git rev-parse --show-toplevel in the base folder before adding
-a worktree; if it does not equal the base folder, the folder is inside another
-repository: stop and ask the user for another folder.
-
-Set the scripts before the commit because Expo prebuild rewrites them to
-expo run:ios and expo run:android; otherwise the dirty worktree blocks removal.
-On npm or network failure, report stderr and stop.
-
-From the base folder, add the tour worktree and run:
-
-  git worktree add -B stim-tutorial/tour "{tour}" HEAD
-  cd "{tour}"
-  stim worktree warm
-  stim guide agent
-
-Apply the guide agent doctor rule before native work: if its STATUS block
-says doctor is due, run stim doctor --platform ios from the tour worktree and
-resolve its findings. No STATUS block means doctor is current. Then run:
-
-  stim start
-  stim ios
-
-Tell the user the first build can take about four minutes on a cold cache.
-Relay the Open in Stim Desktop link printed by stim ios once.
-
-PAUSE: end the turn. Ask the user to look at the Build section, then the
-device, then Logs in Stim Desktop. Without Desktop, use stim status,
-stim stats, and stim logs --errors. Give the next prompt:
-"${TUTORIAL_PROMPTS.rebuild}". Leave the workspace running.`
+Folder safety: if {base} does not exist, clone into it. If it exists, reuse it
+only when all of these hold: app.json has expo.extra.stimTutorial equal to
+${TUTORIAL_VERSION}, git remote get-url origin names ${TUTORIAL_REPO}, git
+rev-parse --show-toplevel equals {base}, and git status --porcelain prints
+nothing. Then skip the clone, install its dependencies (npm ci), run stim doctor
+--platform ios there, and continue at PAUSE. For any other existing folder (another
+repository, local changes, no tutorial marker), stop and ask the user for
+another folder; never overwrite or delete it. Before cloning, check the parent folder:
+create it if absent, then run git -C <parent> rev-parse --is-inside-work-tree.
+If that succeeds, the folder is inside another repository: stop and ask the
+user for another folder. Never git add in the user's repo.
+
+Then, from the parent folder, run:
+
+  git clone https://github.com/${TUTORIAL_REPO}.git stim-tutorial
+
+Check that app.json in the clone has expo.extra.stimTutorial equal to
+${TUTORIAL_VERSION}. If it does not, report the mismatch and stop; the user needs a newer Stim.
+Enter the clone and install its dependencies (npm ci) so the worktrees made for
+the changes inherit them, then run stim doctor --platform ios there: it registers
+the clone with Stim so Stim Desktop sees it, and builds or boots nothing. Do not
+run the app: the clone is only the base for the user's changes; only the optional
+delete step removes it.
+Report the findings of stim doctor and do not act on them: no SimSlim install, no
+--fix, nothing that changes the machine during the tutorial. On npm or network failure, report stderr
+and stop.
+
+${local}
+
+${screenshots}
+
+PAUSE: end the turn. Tell the user to ask for a visual change next, such as
+making the title purple, in their own words. Each change runs in a new linked
+worktree of {base} (stim guide agent), and its first iOS build takes a few
+minutes.`
 			},
-			app: {
-				summary: "Pinned template, verbatim app files, and .gitignore additions",
-				body: () => `TUTORIAL APP
-
-create-expo-app: ${TUTORIAL_PINS.createExpoApp}
-Template: ${TUTORIAL_PINS.template}
-Write the app files verbatim. Append the .gitignore lines to the template's
-existing file. App log lines start with [stim:tutorial]. Crash me raises an
-uncaught JavaScript error, and Slow request times a local three-second timer;
-Stim does not capture native network requests.
-
-${Object.entries(TUTORIAL_FILES).map(([name, content]) => `${name}\n\n\`\`\`${name.endsWith(".json") ? "json" : name.endsWith(".js") ? "js" : "text"}\n${content}\`\`\``).join("\n\n")}`
-			},
-			rebuild: {
-				summary: "Repeat the iOS build and explain the cache result",
-				body: () => `REBUILD
-
-${paths}
-
-Run the same build again, never with --no-build-cache:
-
-${commands("rebuild")}
-
-Read this workspace's environments[].lastBuilds.ios.cacheHit from
-stim status --json, and the miss reason printed by stim ios. Explain a local or remote hit, or the actual miss
-reason when cacheHit is false. A repeat run can miss; report the evidence.
-
-PAUSE: end the turn. Point at the Build section and cache badge, or stim stats.
-Ask the user to open the device's live view and tap Log an error; without
-Desktop use the simulator. Then inspect Logs or stim logs --errors. Crash me
-and Slow request are optional: the former shows a red box, the latter prints
-a timing line. Give the next prompt: "${TUTORIAL_PROMPTS.agent}".`
-			},
-			agent: {
-				summary: "Record a tap and screenshot, replay it, and inspect agent logs",
-				body: () => `AGENT ACTIONS
-
-${paths}
-
-Set {stateDir} to this workspace's agentDevice.stateDir from stim ios or
-stim status --json. Replace <ios.udid> with this workspace's ios.udid from
-stim status --json. Use that exact owned simulator, not a guessed one.
-Run from the tour worktree:
-
-${commands("agent").replace("read -r iosUdid", "iosUdid=\"<ios.udid>\"")}
-
-Use --save-script=tutorial.ad with the equals sign: agent-device treats a
-separate path as a URL and refuses. The dismiss-overlay step clears a red box that would cover the buttons.
-Replay with the same --platform and --udid so its steps reach the agent log.
-Remove the target-v1 evidence and dismiss-overlay lines before replay: replaying
-them can fail with REPLAY_DIVERGENCE on the recorded button identity.
-The scripts and screenshot stay in the tour worktree and are git-ignored.
-
-PAUSE: end the turn. Point at Agent Actions, or the agent log records just
-printed. Expect another error-button line after replay. When screen recording
-is enabled, the user can scrub Replay in Desktop. Give the next prompt:
-"${TUTORIAL_PROMPTS.refresh}".`
-			},
-			refresh: {
-				summary: "Change the title to purple and verify Fast Refresh through logs",
-				body: () => `FAST REFRESH
+			finish: {
+				summary: "Stop and remove the two tutorial worktrees, keeping the clone",
+				body: () => `FINISH
 
 ${paths}
 
-Set TITLE_COLOR in theme.js to '#7c3aed' (purple). Wait a few seconds for
-Fast Refresh, without reloading the app:
-
-${commands("refresh")}
+The worktrees to remove are the two the tutorial tracked: the linked
+worktrees of {base} made for the user's changes. The finish request names them
+as {tour} and {second}. Never touch any other worktree, an earlier tutorial
+clone, or the clone itself. For each, stop from its path, then remove it from
+the clone:
 
-The line [stim:tutorial] title color=#7c3aed is the proof that the edit reached
-the app. The intentional button errors may still be in the error log; check
-whether the edit introduced a new error.
+${commands("finish")}
 
-PAUSE: end the turn. Point at the purple title in the device view or simulator
-and the title color log line. Phone viewing and an approved remote Mac are
-optional user steps; skip them if unwanted. Never pair, approve, or grant
-anything. If the user names an approved machine, the next prompt is
-"${TUTORIAL_PROMPTS.machine}". Otherwise give
-"${TUTORIAL_PROMPTS.finish}".`
+Use a plain remove first. The user's finish request says they do not need the
+changes, which is the consent stim guide agent asks for before worktree remove
+--force, for exactly those two paths: if the plain remove refuses one of them
+only because of uncommitted changes or commits found nowhere else, remove that
+worktree with --force. Never use --force on the clone or on any other
+worktree, and on any other refusal report it and stop. Keep the clone: the
+optional delete step removes it only when the user asks (stim guide tutorial
+delete).
+
+If archive is enabled, tell the user the worktrees appear under Archived in
+Stim Desktop. With archive disabled, report removal without promising an
+archive. Without Desktop, inspect stim status --json for the removed
+environments. End the turn.`
 			},
-			machine: {
-				summary: "Optionally build using a machine the user names and has approved",
-				body: () => `REMOTE MAC (OPTIONAL)
+			delete: {
+				summary: "Remove the tutorial worktrees and the clone through Stim, then delete the folder",
+				body: () => `DELETE THE TEST APP (OPTIONAL)
 
 ${paths}
 
-Proceed only when the user names an approved remote Mac. Substitute that
-name for {machine}. Never approve, pair, or grant anything. If none is named,
-ask for the name or let the user skip this step.
-
-${commands("machine")}
-
-This step bypasses the artifact cache so the build can use the named machine.
-A named machine refuses without a local fallback. If it refuses, report the
-refusal and offer --remote-build auto or local; do not retry silently.
-
-PAUSE: end the turn. Point at the build's machine in Desktop or its report in
-stim status --json. Give the next prompt: "${TUTORIAL_PROMPTS.finish}".`
-			},
-			finish: {
-				summary: "Revert the tutorial edit, stop, and remove only the tour worktree",
-				body: () => `FINISH
-
-${paths}
+Only on the user's explicit request, which the delete prompt is. It covers
+{base} and its linked worktrees, nothing else. Remove them through Stim so their
+simulators, Metro ports and Stim records are torn down before the files go.
 
-The user's finish request authorizes removing this tour worktree only.
-Revert the refresh edit before removal; worktree remove refuses dirty trees.
-Stop from the tour path, then remove from the base checkout:
+First check that {base}/app.json has expo.extra.stimTutorial. If it does not,
+{base} is not the tutorial clone: report it and stop.
 
-${commands("finish")}
+List the worktrees with git -C "{base}" worktree list. For each linked worktree
+(every entry except {base} itself), run stim stop from its path, then
+stim worktree remove "<path>" from {base}. Never use --force here: the delete
+request does not say which changes the user can lose. If a remove refuses, report
+it and stop without deleting anything, so the user can decide about that
+worktree.
 
-Never use --force. On a refusal, report it and stop. Keep the base folder
-and branch. Print these optional cleanup commands for the user; do not run. Deleting
-the base folder also removes the branch, so they are alternatives:
+Then, from {base}, run stim stop and stim worktree remove "{base}". On the
+source checkout it reclaims the Stim environment and leaves the files. If it
+refuses, report it and stop. Only after it succeeds, from the parent folder,
+delete the clone:
 
   rm -rf "{base}"
-  git -C "{base}" branch -D stim-tutorial/tour
 
-If archive is enabled, tell the user the tour appears under Archived in Stim
-Desktop. With archive disabled, report removal without promising an archive.
-Without Desktop, inspect stim status --json for the removed environment and,
-when enabled, its archived entry. End the turn.`
+Never use --force in this step, and never delete any path other than {base}. Report
+what you removed and end the turn.`
+			},
+			share: {
+				summary: "Optionally open a public pull request with before and after screenshots of the change",
+				body: () => `SHARE YOUR FINISH (OPTIONAL)
+
+Only on the user's explicit request, which the share prompt is, and before the
+finish step removes the worktrees. The pull request is public: the user's GitHub
+name and change appear on ${TUTORIAL_REPO}, and a bot replies and closes it. It
+needs gh signed in. Never open it unprompted or from any other step.
+
+Work from the worktree holding the user's change, {tour}. Commit only the
+change's files there, never .expo/screenshots/. Fork the repository and push the
+branch to the fork, since the user has no write access:
+
+  gh repo fork ${TUTORIAL_REPO} --remote --remote-name fork
+  git push -u fork HEAD
+
+Screenshots: use .expo/screenshots/before.png and .expo/screenshots/after.png from that
+worktree (stim guide tutorial run). If either is missing, take it now on the same
+device, that worktree's ios.udid from stim status --json, never booted, with the
+app running from the branch (run it again first if needed). For
+a missing before, show the original screen with
+git checkout origin/main -- <changed files>, capture it once Fast Refresh applies,
+then restore the change with git checkout HEAD -- <changed files> and capture the
+after again with the same tool, so both match in size.
+
+Body: write .expo/screenshots/body.md from the clone's
+.github/pull_request_template.md, keeping its headings, table and Stim link and
+dropping its <!-- --> comments. An older clone without the template gets the
+same parts, in this order:
+- the first line: one sentence saying what changed and why;
+- the table, with ![Before](./.expo/screenshots/before.png) and
+  ![After](./.expo/screenshots/after.png) in its cells;
+- a How it was verified section, with only what you observed: Device is ios.name from
+  stim status --json; Readiness is the "app reported ready" time stim ios
+  printed; Build is lastBuilds.ios.durationMs and whether lastBuilds.ios.cacheHit
+  was local or remote (a cache hit) or false (a full build), plus, when you know
+  it, whether the second worktree's first iOS build was a cache hit; Logs is the
+  result of stim logs --errors. Drop a line you did not observe rather than
+  guess it;
+- the closing line: Built and verified with [Stim](https://github.com/appandflow/stim).
+
+Open the pull request from {tour}:
+
+  gh pr create --repo ${TUTORIAL_REPO} --title "<the one-line summary>" \\
+    --body-file .expo/screenshots/body.md \\
+    --attach ".expo/screenshots/before.png#Before" --attach ".expo/screenshots/after.png#After"
+
+--attach uploads each image and rewrites the matching ./.expo/screenshots/ reference in
+the body to the uploaded file, so the table shows both images. gh 2.99.0
+(2026-09-01) has --attach; confirm with gh pr create --help rather than guessing
+a version. When gh has no --attach, open the pull request with --body-file alone
+and tell the user to drag the two images into the table on GitHub. Give the user
+the pull request URL.`
 			},
 			restart: {
-				summary: "Remove the existing tour safely and repeat from the worktree step",
+				summary: "Start the tutorial again without removing anything",
 				body: () => `RESTART
 
 ${paths}
 
-For "${TUTORIAL_RESTART_PROMPT}", if the tour worktree is present, revert
-the refresh edit, stop, and remove it using the finish section's commands:
-
-${commands("finish")}
-
-Never use --force. On a refusal, report it and stop. Keep the base repository.
-Read stim guide tutorial run, recheck its folder and repository safety rules,
-and redo run from the worktree step. Pause after the build as run instructs.`
+For "${TUTORIAL_RESTART_PROMPT}", remove nothing: the user may still want the
+earlier worktrees. Finish only removes the pair named in its request, so leave
+any earlier worktrees and tell the user they stay until they ask for each by
+path; never use --force for them. Reuse the clone at {base} only if its
+stimTutorial marker equals ${TUTORIAL_VERSION}; otherwise follow stim guide
+tutorial run into a fresh folder. Pause as run instructs. Stim Desktop starts
+over: only worktrees and builds after the restart count.`
 			},
 			manual: {
-				summary: "Commands for every step, including heredocs for the app files",
+				summary: "The commands behind each step, for typing yourself",
 				body: () => `MANUAL TUTORIAL
 
 ${paths}
 
-These commands are for a person typing them, one step at a time,
-as scripts: save a block to a file and run it with sh -e, so it stops on the
-first failure. Read stderr and do not continue to later commands. Follow stim guide tutorial run for folder and repository
-safety. Reuse only this version's tutorial app, never overwrite another folder.
-The creation block skips writes on reuse and checks the repository root.
-
-Replace {base} and {tour} with absolute paths; {base} must end in stim-tutorial. For Agent Actions, replace
-{stateDir} with agentDevice.stateDir from stim ios or stim status --json;
-when read -r iosUdid waits, type this workspace's ios.udid from that status.
-For the optional machine step,
-replace {machine} with a machine you have already approved, or skip it.
-
-Look at the sidebar during warm and Build during the first build (about four
-minutes on a cold cache). Compare cacheHit and missReason on rebuild. At Live
-view and control, open the device viewer and tap Log an error; without Desktop
-use the simulator. At App Logs, try Crash me or Slow request if wanted. A JS
-crash shows a red box; the slow request is a local timer, not network capture.
-At Watch on Your Phone, optionally open an already paired Stim phone to see
-the tour workspace; phone setup and machine approval stay with you.
-Use stim status, stim logs --errors, and stim stats without Desktop.
-
-${TUTORIAL_STEPS.map((step) => `${step.title}${step.optional ? " (optional)" : ""}\n\n${step.manual.length ? `\`\`\`sh\n${step.manual.join("\n")}\n\`\`\`` : "Observe this step in Stim Desktop, or skip it without Desktop."}`).join("\n\n")}
-
-Finish removes only the tour worktree. Never use --force; report a refusal.
-With archive enabled, find the tour under Archived in Desktop or archived[]
-in stim status --json. Keep the base repository and branch. To delete them,
-read stim guide tutorial finish for commands to review and run yourself.`
+Replace {base}, {tour} and {second} with absolute paths: {base} is the clone,
+{tour} the first worktree and {second} the second. For Agent Actions, replace
+{stateDir} with agentDevice.stateDir from stim ios or stim status --json and
+{udid} with the workspace's ios.udid. Clone with git
+clone https://github.com/${TUTORIAL_REPO}.git into a fresh folder outside any
+repository. Each change runs in its own worktree of that clone (stim guide
+agent); the clone itself is never run. Run each worktree on iOS with
+stim ios --remote local --remote-build local so it stays on this Mac.
+
+${TUTORIAL_STEPS.map((step) => `${step.title}${step.optional ? " (optional)" : ""}\n\n${step.commands.length ? `\`\`\`sh\n${step.commands.join("\n")}\n\`\`\`` : "Ask your agent in your own words, or observe this step in Stim Desktop."}`).join("\n\n")}
+
+Finish removes only the two tutorial worktrees, never the clone; stim guide tutorial finish says when --force is allowed for them.`
 			}
 		}
 	}
@@ -10409,7 +10733,7 @@ function renderIndex(version) {
 	return lines.join("\n");
 }
 function guideCommand(program, version, status = (running) => guideStatus({
-	projectRoot: findProjectRoot$1(process.cwd()),
+	projectRoot: findProjectRoot(process.cwd()),
 	running
 })) {
 	program.command("guide [topic] [section]").description("Print reference documentation for THIS version of Stim (topics: " + topicNames().join(", ") + "). A topic with sections prints its section index; name a section to print only it, e.g. `stim guide errors STIM_NO_METRO` or `stim guide lifecycle builds`. Generated by the binary, so it cannot drift from the installed CLI.").action(async (topic, section) => {