stim 1.19.0 → 1.20.0

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

@@ -1,7 +1,8 @@
-import { r as findProjectRoot } from "./project-B5eQ1USs.mjs";
-import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-CxgngUZk.mjs";
-import { s as RECENT_LAUNCH_MS } from "./watchman-BL1IdOtq.mjs";
-import { o as guideStatus, t as WATCHMAN_NESTED_WORKTREES } from "./doctor-watchman-wZhyTdp4.mjs";
+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
@@ -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
@@ -1464,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
 
@@ -1733,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
@@ -1826,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,
@@ -1846,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:
@@ -2025,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:
 
@@ -2441,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
@@ -2451,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
@@ -2469,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,
@@ -2650,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.`
@@ -2879,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
@@ -2950,11 +3016,11 @@ 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
@@ -3117,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
@@ -3579,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.`
@@ -4255,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
@@ -4285,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
@@ -4746,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
@@ -4821,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
@@ -4985,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
@@ -4996,6 +5072,121 @@ 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
@@ -5059,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.
 
@@ -5069,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>.
@@ -5079,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
@@ -5275,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.
@@ -5283,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
@@ -5956,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)
@@ -6006,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
@@ -6021,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.
@@ -6063,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
@@ -6982,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.
@@ -7197,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\` --
@@ -7287,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
@@ -7335,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
@@ -7716,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
@@ -8232,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
@@ -8244,6 +8479,19 @@ KEYS STIM READS
                         "auto" places on an approved Mac when this Mac is full or
                         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
@@ -8354,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
@@ -8369,20 +8637,36 @@ ${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; "local"
@@ -8416,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.
@@ -8766,7 +9065,7 @@ simulator sessions on, by MagicDNS name with an optional serve port (default
   stim doctor --fix
 
 Automatic membership is separate from approval. In Desktop Settings > Remote Macs,
-use Automatic builds and Automatic simulators for this Mac or a configured remote.
+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"]'
@@ -8949,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
@@ -9381,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
@@ -9955,15 +10254,16 @@ 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}, {worktrees} and
-* {machine} are filled in by Desktop. Only the first and last name a guide section, which holds the folder and cleanup safety rules.
+* 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 install its dependencies, then run stim doctor for iOS there so Stim registers it. Use a fresh folder: if {base} already exists or is inside another git repository, stop and ask me for another folder, and never git add in my own repo. Follow stim guide tutorial run.`,
+	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.",
-	machine: "Build the app for iOS on {machine} with stim instead of on this Mac. Do not approve or pair anything.",
 	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.",
-	share: `Open a pull request to ${TUTORIAL_REPO} with my title color change, and include a screenshot of it running in the simulator. See stim guide tutorial share.`,
+	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 = [
@@ -9981,7 +10281,7 @@ const TUTORIAL_STEPS = [
 		title: "Make a Change",
 		who: "you",
 		optional: false,
-		ask: null,
+		ask: TUTORIAL_ASKS.build,
 		section: null,
 		commands: []
 	},
@@ -10037,15 +10337,6 @@ const TUTORIAL_STEPS = [
 		section: null,
 		commands: []
 	},
-	{
-		id: "machine",
-		title: "Build on Another Mac",
-		who: "both",
-		optional: true,
-		ask: TUTORIAL_ASKS.machine,
-		section: null,
-		commands: ["cd \"{tour}\"", "stim ios --remote local --remote-build \"{machine}\" --no-build-cache"]
-	},
 	{
 		id: "share",
 		title: "Share Your Finish",
@@ -10055,11 +10346,16 @@ const TUTORIAL_STEPS = [
 		section: "share",
 		commands: [
 			"cd \"{tour}\"",
-			"git commit -am \"Tutorial change\" -m \"Build <time>, second build cache <hit or miss>\"",
-			"xcrun simctl io {udid} screenshot finish.png",
+			"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} --fill --attach "finish.png#The change running in the simulator"`
+			`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"`
 		]
 	},
 	{
@@ -10078,6 +10374,23 @@ const TUTORIAL_STEPS = [
 			"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
@@ -10090,6 +10403,23 @@ 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).commands.join("\n");
 }
@@ -10114,7 +10444,7 @@ const TOPICS = {
 		preamble: () => `STIM TUTORIAL
 
 The tutorial clones ${TUTORIAL_REPO}, a tiny Expo app, into {base}; the clone is
-never run or removed. The user then asks for a visual change, and for another
+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
@@ -10126,6 +10456,7 @@ ${local}
 
 "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}
@@ -10139,8 +10470,14 @@ For commands to type yourself, read stim guide tutorial manual.`,
 
 ${paths}
 
-Folder safety: use a fresh folder. If {base} exists, stop and ask the user for
-another folder; never overwrite or delete it. First check the parent folder:
+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.
@@ -10154,13 +10491,16 @@ ${TUTORIAL_VERSION}. If it does not, report the mismatch and stop; the user need
 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 and is never removed.
+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
@@ -10185,18 +10525,47 @@ 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. Print
-these optional cleanup commands for the user; do not run them:
-
-  rm -rf "{base}"
+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.`
+			},
+			delete: {
+				summary: "Remove the tutorial worktrees and the clone through Stim, then delete the folder",
+				body: () => `DELETE THE TEST APP (OPTIONAL)
+
+${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.
+
+First check that {base}/app.json has expo.extra.stimTutorial. If it does not,
+{base} is not the tutorial clone: report it and stop.
+
+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.
+
+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}"
+
+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 a screenshot of the change",
+				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
@@ -10204,31 +10573,50 @@ 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 the change
-there, fork the repository and push the branch to the fork, since the user has
-no write access:
+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
 
-Screenshot: take a PNG under 1 MB of the app showing the change, with
-agent-device screenshot when it is installed, otherwise
-xcrun simctl io <ios.udid> screenshot finish.png, using the udid of that
-worktree from stim status --json, never booted. If the app is no longer
-running, run it again from the branch first.
-
-Open the pull request with gh pr create --repo ${TUTORIAL_REPO} --fill. Put one
-short line with the build time and whether the second worktree's first iOS build
-was a cache hit, when you know them from stim status --json or stim stats, in the
-commit message body (git commit -m "<title>" -m "<that line>"), so --fill carries it
-into the pull request body.
-
-Attach the screenshot with gh: gh pr create --attach "finish.png#The change
-running in the simulator" uploads the image and appends it to the body. 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, commit the PNG on the PR branch as
-finish/<github-login>.png before pushing and embed it in the body with a
-relative link: ![the change](finish/<github-login>.png).`
+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: "Start the tutorial again without removing anything",
@@ -10253,8 +10641,7 @@ ${paths}
 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. For the optional machine step, replace
-{machine} with a machine you have already approved, or skip it. Clone with git
+{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