stim 0.0.0 → 1.1.0

package/dist/guide-DrhrDBo5.mjs

@@ -0,0 +1,4319 @@
+import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-BSwrY4FZ.mjs";
+import chalk from "chalk";
+//#endregion
+//#region src/guide/index.ts
+const TOPICS = {
+	agent: {
+		summary: "The normal coding-agent workflow, safety rules, and topic routing",
+		body: () => `AGENT WORKFLOW
+
+Use Stim to run React Native and Expo apps without sharing a Metro port or
+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.
+
+TWO WORKFLOWS
+
+SINGLE CHECKOUT: work in place, on whatever branch the task needs, in one
+directory. start, ios, android, logs, stop, and never a linked worktree. That
+directory is your workspace, and no rule below about keeping the source checkout
+fit as a seed applies to it.
+
+WORKTREE: the checkout you cloned is a seed. It stays clean and on the default
+branch, and every task gets a linked worktree warmed from it. In this workflow
+the source checkout is infrastructure, not a workspace: you edit, build, and run
+in the worktree, and you keep the seed fit to copy. Every rule below about the
+source checkout's fitness as a seed belongs to this workflow.
+
+Doctor reports that fitness -- how far behind the seed is, uncommitted tracked
+changes, an interrupted rebase or merge, a detached HEAD, a diverged branch, a
+branch that is not the default one -- only once the repository has at least
+one linked worktree, so read it from inside the worktree. A single-checkout
+session is never told that its own branch is a problem.
+
+NORMAL WORKFLOW
+
+Work in the current checkout by default. When the task needs another branch or
+an isolated environment, take the worktree workflow: create a linked worktree
+with Git and warm its ignored state. If a harness already created this linked
+worktree, run stim worktree warm here instead of creating another one. It
+copies missing ignored paths from the source checkout, including eligible .env
+and local configuration files. It preserves the branch, tracked files, and
+every existing destination entry; existing ignored directories are skipped
+whole, not filled in. Add --refresh to fast-forward the source checkout and
+install what moved there before the copy; it refuses a source checkout with local
+work and never switches branches. Read guide lifecycle options for exclusions
+and incomplete-copy remedies.
+
+Wait for warm to exit successfully (exit code 0) before running stim start,
+stim ios, stim android, or a dependency install in that worktree. If the shell
+tool returns a running session or job ID, poll or wait for that job to finish;
+the ID is not completion. Concurrent writes to the destination are unsafe:
+warm checks for existing entries before copying, not during the copy. Do not
+edit files, install dependencies, or run another warm in that worktree until
+it finishes; concurrent files can be overwritten or removed.
+If warm fails or reports incomplete, resolve the reported failure first.
+
+Before native worktree work, run doctor for the platform in scope. It checks
+the source checkout from a linked worktree. Fix relevant findings and inspect the
+upstream gap; in the single-checkout workflow those seed findings do not
+appear. It also prints the running CLI version and the stim installation
+resolved from PATH. If that resolved installation is older than another one,
+fix PATH or the installation before continuing so commands and guidance match.
+Doctor reports cross-volume staging and build-cache copies; read guide settings
+for placement overrides and guide lifecycle options for warm behavior.
+For iOS Debug architecture findings, review the project's overrides and imported
+Podfile helpers using guide lifecycle options. Doctor --fix does not change them.
+For a linked native library carrying Git metadata, add the printed .git entries to
+.fingerprintignore only when the native build does not read Git state.
+
+  stim doctor --platform ios          # or: --platform android
+
+For stale Android CMake launcher findings, stop native builds and run
+stim doctor --fix --platform android in the affected checkout before warming
+more worktrees. It removes affected ignored, untracked generated .cxx
+configurations, including installed native modules; the next build recreates
+them. It preserves source, custom launcher settings, and the shared ccache.
+
+  # Skip Git creation if the harness already created this linked worktree.
+  git worktree add -b <branch> <worktree-path> HEAD
+  cd <worktree-path>
+  stim worktree warm
+
+  stim start
+  stim ios                             # or: stim android
+
+  # Reproduce the affected behavior and capture the baseline errors.
+  stim logs --errors
+
+  # If a native process exits with no report, inspect the captured device output.
+  # An empty query is not proof that a crashed app was healthy.
+  # See guide logs for JS/native symbolication and capture limits.
+
+  # Edit JavaScript or TypeScript; Fast Refresh applies the change.
+  # For UI work, wait for the expected UI and repeat the affected interaction
+  # on the reported device. Keep using the existing automation session, if any.
+  stim logs --errors
+  # Retain proof before cleanup: a screenshot, recording, or relevant runtime output.
+
+  stim stop
+  stim worktree remove
+
+RULES DURING THE LOOP
+
+- Run Stim from the app directory: the one whose package.json depends on
+  react-native or expo. Anywhere else -- a monorepo root, a tools package --
+  start, ios and android refuse with STIM_NO_PROJECT naming that package.json,
+  and doctor reports it as a finding.
+- Put runtime .stim.json beside that app's package.json. Monorepo apps do not
+  inherit a repository-root runtime file. Keep repository-wide worktree-copy
+  rules at the source checkout root; see guide settings for the two scopes.
+- Run start before a debug ios or android build. If it returns STIM_NO_METRO,
+  run stim start and retry.
+- Run ios or android again after a native input changes. A JavaScript-only
+  change does not need one.
+- For stale Metro transforms or file-map state, use stim start --reset-cache.
+  It restarts only this app's verified owned Metro, preserving devices and other
+  apps' caches. See guide lifecycle for reset scope and Expo requirements.
+- Reload is not part of the normal workflow. Use stim reload on an owned local
+  simulator or emulator when an error screen remains after the fix, and on
+  Android after a failed first bundle load. It reloads JavaScript and never
+  restarts the app. An iOS app whose first bundle failed never connects to
+  Metro, so reload cannot reach it and says to use the device's own Reload
+  control. For a physical device that reached Metro, use agent-device metro
+  reload with the reported port. The detected iOS Local Network first-load
+  remedy uses UI automation instead because that app never established a Metro
+  connection.
+- A successful stim reload confirms that the request was sent, not that new
+  JavaScript loaded or the screen recovered. Verify the expected UI on the
+  reported device and inspect stim logs --errors before claiming recovery.
+- If launch reports an app error but also says the native process is alive,
+  the app did not crash. Fix JavaScript or TypeScript and use Fast Refresh. If
+  the error screen remains, follow the printed reload remedy instead of
+  running ios or android again. If launch says FATAL because the app process exited,
+  fix the crash and run the platform command again; Metro cannot restart it.
+- A native build can outlive a shell timeout. Retry the same command and
+  follow its printed remedy if waiting times out. See guide lifecycle concurrency.
+- ios and android install the app, launch it, and check readiness. Trust the
+  exact device, app, Metro, and launch facts in the final summary. Use the full
+  reported device ID. Never assume a simulator named booted belongs to this
+  workspace.
+- After each ios or android run, give the user one compact result: exact device,
+  app id, launch state, cache result, total duration, and whether stim logs
+  --errors passed. Include a remedy only when action remains. Do not repeat the
+  phase transcript.
+- An OK summary with no launch qualifier proves the launch. "bundle requested,
+  still building" means Metro has not finished; wait and query the logs. For
+  launch UNVERIFIED, follow the printed remedy before claiming success. JSON
+  reports these as true, "bundling", and "unverified" in launched.
+  WARNING means the native launch completed with app errors, or an app readiness
+  signal was expected but not confirmed; inspect the output before claiming a healthy UI.
+- A clean logs --errors check requires exit code 0 AND no matching errors in
+  captured logs. Exit code 0 alone means the query succeeded, even when errors
+  were printed. Human output shows "No matching log records" on stderr for
+  zero matches; JSON mode prints zero bytes. This does not prove launch or log
+  capture succeeded. Do not read the NDJSON files directly.
+- Use stim status when resuming a workspace or recovering missing device,
+  port, server, or build facts. A normal start and platform run already print
+  them. Use stim doctor when a build is unexpectedly slow or the environment
+  looks incomplete.
+
+OWNERSHIP AND DELETION
+
+Stim creates, boots, and deletes only devices it created. Owned simulators use
+the stim-<label> (<model> <runtime>) name. Never point Stim at a user-created
+emulator or simulator.
+
+worktree remove parks the workspace's simulator or emulator for later adoption.
+A parked device is Stim-owned: never delete one by hand. gc --delete clears verified
+entries and keeps failures; see guide lifecycle pool. First launch on a
+physical iPhone can need the one-time taps named by the remedy.
+
+stim android --device [serial] and stim ios --device [udid] install on a
+connected physical device. Stim never creates, boots, shuts down, or deletes
+hardware. It records a temporary lease, not an owned-device registry entry.
+
+A --device run leases that device for the run. stim device lock ios --for 10m
+holds it across runs; stim device unlock gives it back. Never delete another
+workspace's lease file under ~/.stim/device-locks; gc --delete removes expired
+ones.
+
+stop and worktree remove release this workspace's leases. On a physical
+iPhone, stop also closes the app by ending its log collector; it does not
+shut down the phone or uninstall the app.
+
+Treat a refusal as an ownership or state mismatch: read its code and remedy.
+Never reach for --force first.
+Stim leaves externally started servers alone. Stop them with their original
+tool; neither a matching port nor --force grants process ownership.
+
+Ask the user before these actions:
+
+- worktree remove, because it deletes the worktree and gives up its owned
+  device. It works with any linked worktree, warmed or not, without requiring
+  a Stim registry entry. Git-created branches are kept; a branch with an
+  existing Stim ownership record is deleted only when it has no unique commits.
+- worktree remove --force, because it also discards uncommitted and untracked
+  files.
+- gc --delete, because it deletes orphaned resources. gc --delete --cache all
+  empties the shared build caches instead; it inspects nothing else.
+- stop when the workspace owns an EAS session, because it irreversibly ends
+  that remote session. For a local device, stop shuts it down but does not
+  delete it. An explicit stop shuts down a Stim-owned simulator even when
+  another process uses it. It never shuts down an unowned simulator.
+
+SANDBOXES
+
+An agent harness that sandboxes shell commands usually permits writes inside
+the project and little else. Stim also needs writes to STIM_HOME (~/.stim by
+default), simulator service access, and local access to the adb server. When
+those sit outside the harness allowlist, the failure looks like an unwritable
+directory or unavailable device service rather than a broken machine. Decide
+at the start of a session whether to run Stim outside the sandbox or ask the
+user to allow those operations. guide errors sandbox lists the exact
+requirements.
+
+LOAD ADVANCED GUIDANCE WHEN NEEDED
+
+  stim guide                      # list topics
+  stim guide errors               # index of every refusal code and message
+  stim guide errors <CODE>        # one refusal, e.g. stim guide errors STIM_NO_METRO
+  stim guide errors sandbox       # running under a sandboxing harness
+  stim guide errors unverified    # launch unverified, and the Local Network reason
+  stim guide errors fallbacks     # swap, cache, and install notes on a release cache hit
+  stim guide lifecycle            # the ordered flow, consent rules, and capacity
+  stim guide lifecycle verification # reproduce, edit, verify the UI, and retain proof
+  stim guide lifecycle readiness  # add optional app readiness logs; no package required
+  stim guide lifecycle builds     # build optimizations, optional cache warm-up, fingerprints
+  stim guide lifecycle concurrency # shared builds, wait timeouts, capacity limits
+  stim guide lifecycle options    # every flag, Android variants, --device-type, --system-image
+  stim guide lifecycle devices    # ios --device and android --device on a physical phone
+  stim guide lifecycle release    # Release configurations and ...Release variants
+  stim guide facts                # the --json payloads
+  stim guide facts devmenu        # the Expo dev menu or Tools button over the app
+  stim guide metro                # supervisor, custom Metro, tunnels, and remote devices
+  stim guide logs                 # filters, record shape, and capture limits
+  stim guide cleanup              # what reclaims a device, and what deletes
+  stim guide cleanup collector    # an unproven collector pid; why the app on a phone closed
+  stim guide settings             # configuration files and supported keys
+
+A refusal prints a CODE such as STIM_NO_METRO. Run stim guide errors <CODE>
+with the code exactly as printed and read only that section; every code in a
+shared header (STIM_BAD_ARG / STIM_NO_PROJECT) resolves to the same section. A
+refusal with no code is quoted by message in stim guide errors. A topic with
+sections called bare prints its section index, so read the narrowest section
+before release configurations or Android variants; remote devices; custom
+Metro processes or tunnels; cache misses, bypasses, or concurrent builds;
+capacity limits; cache statistics from stim stats; worktree carry-over;
+fingerprint exclusions; gc; --force; cleanup failures; or unfamiliar states
+and error codes. Ordinary stim stop and an authorized clean
+stim worktree remove do not need the cleanup guide.`
+	},
+	facts: {
+		summary: "The --json payloads: `start`, `ios`, `android`, `reload`, `stop`, `status`, `doctor`, `device lock`/`unlock`, and the error contract",
+		preamble: () => `FACTS CONTRACT
+
+\`start\`, \`ios\`, \`android\`, \`reload\`, \`stop\`, \`status\`, \`stats\`, \`doctor\`,
+and \`device lock\`/\`device unlock\` each print exactly ONE line of JSON on
+stdout for \`--json\`. Every other line goes to stderr, so it is always safe
+to pipe. \`logs --json\` is the one exception: it is NDJSON, one record per
+line by design (see \`guide logs\`), not this single-payload contract.`,
+		sections: {
+			payloads: {
+				summary: "every field of the start, ios, android and reload payloads, the error contract, the device rules",
+				body: () => `  stim start --json
+
+  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\`)
+  logsDir         where the NDJSON timeline is written
+  alreadyRunning  true when nothing needed starting
+
+  stim ios --json
+
+  platform        "ios"
+  udid            the owned simulator this workspace installed onto, or the
+                  phone's UDID on \`--device\`. A physical device gets no
+                  owned-device registry entry; its ID is stored in a temporary
+                  lease. \`stop\` releases workspace leases and \`gc --delete\`
+                  removes expired lease files
+  deviceName      its name, or null
+  deviceType      the owned simulator's MODEL, as
+                  \`xcrun simctl list devicetypes\` names it ("iPad Pro 13-inch
+                  (M4)"). Read from the simulator itself, so a run driven by
+                  the ios.deviceType setting reports it too, not only a
+                  \`--device-type\` run. Null on \`--device\` and on a
+                  simulator Stim does not own
+  runtime         that simulator's iOS runtime version ("18.5"), from the same
+                  record. Null on the same paths as deviceType
+  fingerprint     the @expo/fingerprint hash of the native inputs, AS STORED.
+                  A run that had to \`expo prebuild\` or \`pod install\`
+                  rewrote fingerprinted files while it worked (the generated
+                  native directory, package.json's scripts, the app config,
+                  Podfile.lock), so the hash it looked up is not the hash the
+                  tree has afterwards. The artifact is stored under the hash
+                  computed AFTER those steps -- the one the next run in this
+                  tree computes -- and this field reports that one. The shift
+                  is printed on stderr as one dim line naming both short
+                  hashes. A prebuild shift is RE-LOOKED-UP before anything
+                  compiles (\`cache
+                  hit 6564e2.. (post-prebuild key)\`), so a cold tree -- a
+                  fresh worktree or clone of a CNG app -- installs an entry
+                  another workspace already built instead of compiling
+                  beside it. Android also fingerprints after Gradle because
+                  Gradle plugins can rewrite native inputs while they build;
+                  its artifact is stored only under that post-build hash. A
+                  stable second fingerprint prints no shift line. If the iOS
+                  fingerprint after prebuild or pod install, or the Android
+                  fingerprint after Gradle, cannot be computed, the build is
+                  installed but not cached, and fingerprint and cacheKey are null
+  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
+  cacheKey        the shared-build-cache key derived from it (the
+                  configuration is part of it: -release-sim vs -debug-sim)
+  cacheHit        WHICH LEVEL answered, not a boolean:
+                    "local"   this machine's shared cache (free, instant)
+                    "remote"  the project's own Expo buildCacheProvider (a
+                              download; it is copied into the local cache on
+                              the way past, so the next workspace is "local")
+                    false     nothing answered, so it was compiled
+  webPreviewUrl   only on a remote device that has one (an EAS Simulator
+                  session): a browser URL showing that device's screen. Absent
+                  on a local device. Hand it to the human -- it is the only way
+                  to see a device that is not on this machine. Never open it ON
+                  the device; it is a page, not a deep link.
+  cacheSkipped    true only when --no-build-cache was passed: "nothing was
+                  looked up", which is a different fact from "nothing was found"
+  compilationCache
+                  Xcode compilation-cache activity for a compiled iOS app:
+                    { status: "reported", hits, cacheableTasks, hitRatePercent }
+                  status is "not-run" when the artifact cache supplied the app.
+                  status is "unavailable" when Xcode did not print reliable
+                  statistics. This field is separate from cacheHit
+  waitedForBuild  { pid, ms } when ANOTHER workspace was already compiling this
+                  exact fingerprint and this run waited for its artifact instead
+                  of compiling a second copy
+                  (see \`guide lifecycle concurrency\`); null when nothing was
+                  waited for.
+                  cacheHit is "local" either way -- the artifact did come from
+                  the local cache -- so this is what separates "it was already
+                  there" (free) from "it was there twelve minutes later" (still
+                  cheaper than a second build). Both commands carry it
+  appPath         the .app that was installed
+  bundleId        the iOS bundle id that was launched
+  installSkipped  true when the artifact was ALREADY on the device byte for
+                  byte, so nothing was installed and the run went straight to
+                  launch (see \`guide lifecycle builds\`). false means an
+                  install ran.
+                  Always false on \`--device\`: proving a phone already holds
+                  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.
+                                 The command checks process liveness when the
+                                 platform exposes it. Errors from that window
+                                 are printed even when the app stays alive,
+                                 EXCEPT the device log's, which is COUNTED into
+                                 one \`launch\` line instead (see
+                                 \`guide logs\`). The agent decides whether a
+                                 nonfatal error matters.
+                                 IT IS NOT A PAINTED SCREEN. Stim observes the
+                                 bundle and the process, never a frame, and a
+                                 cold app can keep rendering for a minute or
+                                 more after this, which is why the stderr line
+                                 reads \`bundle loaded, process alive, stable
+                                 for 3s -- the first screen may still be
+                                 rendering\`. Poll the UI before you trust a
+                                 screenshot. Optional app-declared readiness
+                                 adds a separate stderr readiness phase; it
+                                 does not change this field. See
+                                 \`guide lifecycle readiness\`
+                    "bundling"   the request DID arrive and Metro was still
+                                 building or delivering when the bundle timeout closed.
+                                 The wiring is proven; the JS has simply not
+                                 run yet (a cold bundle of ~10k modules takes
+                                 longer than the window). Nothing to do --
+                                 no remedy list is printed for it -- and
+                                 \`logs --source metro\` shows the build
+                                 finishing
+                    "unverified" nothing was observed at all: usually a
+                                 dev-client server picker awaiting a tap
+                  See \`guide facts devmenu\` for the dev menu and its button.
+  metroPort       the port the app was wired to; NULL on a non-Debug
+                  configuration, whose JS is embedded and which is launched
+                  with no dev server at all. There, \`launched\` is verified
+                  by the app process staying alive after launch (a bad
+                  embedded bundle crashes within seconds), not by a bundle
+                  request. A process that exits fails the command. An iOS
+                  launch with no process id is "unverified", and
+                  \`stim logs --errors\` has the device log that says why
+  logs            { dir }
+  durationMs      wall time for the whole run
+
+  stim android --json
+
+  platform        "android"
+  serial          the owned emulator (always "emulator-<consolePort>")
+  avdName         the AVD's NAME (stim-<label>). The serial is a slot --
+                  emulator-5554 is whatever booted into that console port
+                  first -- so this is what addresses the emulator in
+                  \`emulator -avd\`, avdmanager, or a device tool. The console
+                  port is CHOSEN AND RECORDED under the global config lock
+                  BEFORE the emulator starts, then passed to it as \`-port\`,
+                  so two workspaces booting at the same moment cannot land on
+                  one serial. A boot that fails releases the port again and
+                  keeps the AVD recorded for \`gc\`
+  deviceName      the same name, matching the iOS payload's field
+  systemImage     the sdkmanager package id the owned AVD was created from
+                  ("system-images;android-36;google_apis;arm64-v8a"), read from
+                  the AVD's own config.ini, so a run driven by the
+                  android.systemImage setting reports it too, not only a
+                  \`--system-image\` run. Null on \`--device\` and on an
+                  emulator Stim does not own
+  fingerprint / cacheKey / cacheHit / cacheSkipped / waitedForBuild /
+  appPath / installSkipped / launched
+                  as above -- cacheKey keys on the VARIANT here
+                  (<fingerprint>-productionrelease-sim). A Debug artifact for
+                  a proven target ABI also ends in that ABI
+                  (<fingerprint>-debug-sim-arm64-v8a)
+  variant         the gradle variant that was built ("productionDebug" from
+                  --variant or the android.variant setting); null for the
+                  default assembleDebug. A variant whose name ENDS IN Release
+                  is a release build: its JS is embedded and no dev server is
+                  used
+  metroPort       the port the app was wired to; NULL on a release-shaped
+                  variant, exactly as on a non-Debug iOS configuration.
+                  There, \`launched\` is verified by the app PROCESS being
+                  alive on the device a moment after launch (\`pidof\`, then
+                  \`ps -A\`), not by a bundle request -- "unverified" means
+                  no process was found fails the command, and
+                  \`stim logs --errors\` has the device log that says why
+  bundleId        the ANDROID PACKAGE NAME the launch, the port wiring and
+                  the remedies all target -- read from the BUILT APK's
+                  manifest, which on a flavored project is the flavor's
+                  applicationId, not what the project files say
+  debugHttpHost   "10.0.2.2:<port>" on an emulator, "localhost:<port>" on a
+                  physical device, when the app's SharedPreferences were
+                  pointed at this workspace's Metro; null when they were not.
+                  A healthy run reverses only <port> -> <port>, which is what
+                  that host resolves to. Only when the write fails does Stim
+                  also reverse 8081 -> <port>, so the app's compiled-in
+                  default still finds this workspace's Metro
+  debugHttpHostNote
+                  why the write did not land, when it did not. A launch
+                  survives it -- this is the difference between the two
+  devClientUrl    the expo-dev-client deep link that was opened, or null for
+                  a plain launcher start. This is the command that puts the
+                  app back on THIS workspace's bundle
+  ccache          the Android C++ compilation cache, the counterpart of the
+                  iOS compilationCache field:
+                    { status: "reported", hits, misses, hitRatePercent }
+                  status is "not-run" when the artifact cache supplied the
+                  APK. status is "unavailable" when no C++ compile went
+                  through ccache -- ccache absent from PATH, a project that
+                  sets its own CMake compiler launcher, or a Gradle run whose
+                  native work was all up to date. None of the three is an
+                  error, and this field is separate from cacheHit
+  logs            the workspace log directory
+  durationMs      wall time for the whole run
+
+  stim reload [ios|android] --json
+
+  Exit 0 and this payload confirm that the reload request was sent. They do
+  not prove that new JavaScript loaded or that the screen recovered. The
+  command does not observe completion. Verify the expected UI on deviceId
+  and inspect stim logs --errors before claiming recovery.
+
+  platform        "ios" | "android"
+  deviceId        the exact owned simulator UDID or emulator serial targeted
+  deviceName      the owned simulator or AVD name
+  appId           the live bundle id or Android package
+  metroPort       the workspace's verified Metro port
+  strategy        how the reload was addressed.
+                  "metro-websocket" -- Metro named its clients and Stim
+                  addressed every peer matching this platform. A workspace
+                  Metro serves one app, so those peers are this app on however
+                  many devices are attached to that port.
+                  "metro-broadcast" -- this Metro cannot name its clients, so
+                  the reload went to all of them and Stim cannot confirm appId
+                  was among them. Verify the UI on deviceId; if it did not
+                  change, reload from the app's own error screen or dev menu
+  targets         how many peers the reload was addressed to, or null when
+                  broadcast. Greater than 1 means several devices are running
+                  this app on that Metro and the request addressed all of
+                  them, not only deviceId. Completion is not observed
+
+  stim doctor --json
+
+  project         the resolved app root
+  platform        "ios" | "android" | null
+  stim            { runningVersion, runningPath, resolved, installations,
+                    versions, highestVersion, resolvedIsOlder }
+                  resolved is the first executable named stim on PATH;
+                  installations contains every distinct real executable on
+                  PATH and the version each reports. resolvedIsOlder is true
+                  only when that first executable is below the highest version
+                  available from this invocation or PATH
+  findings        the diagnostic findings; a lower resolved Stim is a
+                  costs-time finding with a PATH or installation remedy
+
+ON FAILURE
+  \`start\`, \`ios\` and \`android\` all print the error contract instead,
+  still one line on stdout, and exit 1:
+
+    { "code": "STIM_NO_METRO", "message": "...", "remedy": "..." }
+
+  If a native build returned before the failure, this payload also carries
+  \`ccache\` (Android) or \`compilationCache\` (iOS), with the status and
+  counters described above. This includes failed builds and later install
+  or launch failures. The field is absent when no native build returned.
+
+  Branch on \`code\`, never on the message text. \`guide errors\` enumerates
+  every code.
+
+RULES
+  - Never hardcode or guess a udid/serial/port. Read them from the payload.
+  - Pass them EXPLICITLY to every device tool you drive yourself
+    (agent-device, xcrun simctl, adb -s, idb).
+  - Never assume "booted" is your simulator. Other agents have theirs booted
+    too.
+  - Every device Stim creates or boots is one Stim created, named
+    stim-<label> (<model> <runtime>) on iOS. New local device labels combine
+    the git worktree directory and app directory names, e.g.
+    pr6460-tlon-mobile. Equal names collapse to one; outside git, the app
+    directory name is used. An iOS name collision adds the workspace ID
+    after the model and runtime, preserving it when the label is truncated.
+    Existing owned iOS simulators are renamed on reuse. Android keeps
+    existing and adopted AVD names. The exceptions are
+    \`android --device\` and
+    \`ios --device\`, which use a connected physical device Stim never
+    creates, boots, or deletes.`
+			},
+			devmenu: {
+				summary: "why the Expo dev menu or Tools button is or is not over the app, per platform and device kind",
+				body: () => `  EVERY DEV-CLIENT DEEP LINK CARRIES disableOnboarding=1
+  INSIDE ITS PROJECT URL
+  (\`...?url=http%3A%2F%2Fhost%3Aport%2F%3FdisableOnboarding%3D1&disableFab=1\`),
+  and expo-dev-launcher finishes its own dev-menu ONBOARDING
+  when it reads it. That is all the flag does: it sets
+  EXDevMenuIsOnboardingFinished. ON iOS it has to sit on the
+  PROJECT url -- the value of the \`url\` parameter -- because
+  that is the URL the launcher hands to the check; on the
+  outer deep link it does nothing there. Android reads it on
+  either.
+  ON A SIMULATOR, before a local dev-client openurl, Stim
+  preapproves CoreSimulatorBridge for exactly the installed
+  bundle id and discovered scheme on its owned simulator. That
+  suppresses iOS's first-launch confirmation;
+  unrelated schemes remain unapproved. It also writes
+  EXDevMenuShowsAtLaunch=false and
+  EXDevMenuShowFloatingActionButton=false, which the flag does
+  NOT cover, and those together are what keep the menu and its
+  button off a simulator entirely, so device automation opens
+  on the app. The
+  unverified warning therefore leads with the picker, then
+  prints the openurl
+  retry. ON LOCAL ANDROID the same deep link also carries the
+  \`EXDevMenuDisableAutoLaunch\` boolean intent extra, which
+  the launcher reads to set EXDevMenuShowsAtLaunch=false and
+  EXDevMenuIsOnboardingFinished=true. It stops the menu
+  opening automatically, but does NOT set expo-dev-menu's
+  showFab preference, so its floating Tools button can remain.
+  Remote Android opens only the URL, so that intent-extra
+  suppression does not apply there.
+  Every Stim deep link also carries an outer \`disableFab=1\`
+  query parameter. Versions with expo/expo#49651 use that as a
+  session-only override; earlier versions ignore it. Stim does
+  not rewrite expo-dev-menu's private SharedPreferences XML:
+  that internal file is not a supported API, and changing it
+  would persist over the user's own Tools-button setting. The
+  list leads with the supported launch command (\`am start -a
+  android.intent.action.VIEW -d '<devClientUrl>'
+  --ez EXDevMenuDisableAutoLaunch true\`).
+  ON A PHONE NONE OF THAT PREAPPROVAL APPLIES. The
+  preapproval and that write both go
+  through \`simctl spawn defaults write\`, and devicectl has
+  no defaults command; the one file route,
+  \`devicectl device copy to --domain-type appDataContainer\`
+  onto Library/Preferences/<bundleId>.plist with the app
+  terminated, copies successfully and then loses the seeded
+  keys, because cfprefsd serves its cached domain and rewrites
+  the file. THE FLAG ALONE DOES NOT COVER A PHONE:
+  EXDevMenuShowsAtLaunch defaults to TRUE on iOS
+  (DevMenuPreferences.setup), and DevMenuManager arms its
+  auto-launch observer when \`showsAtLaunch ||
+  shouldShowOnboarding()\`, so finishing onboarding clears
+  only the second half. THE LAUNCH ARGUMENTS COVER THE REST.
+  The device launch ends in
+  \`<bundleId> -- -EXDevMenuShowsAtLaunch 0
+  -EXDevMenuShowFloatingActionButton 0\`: devicectl passes
+  everything after \`--\` to the app, and NSUserDefaults reads
+  the argument domain AHEAD of the persisted one, so the menu
+  and its floating button are off for that launch and nothing
+  is written to the phone. So a fresh install comes up on the
+  app, not on the menu, and with no floating button.
+  THE FAB IS REAL ON A PHONE, and a screenshot is the only
+  way to see it: about four seconds after launch a blue gear
+  labelled Tools appears top-right over the app, the label
+  fades after roughly ten seconds, and the gear stays as a
+  translucent grey circle for the life of the app. It carries
+  no accessibility label after the fade, so
+  \`agent-device snapshot -i\` stops listing it. Measured
+  with the argument on: the corner is clean at 4s and at 12s.
+  Stim's own launch is the only one that
+  carries these: an app started ANOTHER way -- a home-screen
+  tap, a relaunch without the arguments -- still gets the
+  stored value, and on a fresh install that is the menu
+  (runtime version, Close, Reload, Go home) and the button.
+  \`agent-device press 'label="Close"'\` dismisses it -- or
+  \`snapshot -i\` and the ref. The onboarding key the flag
+  writes and the Local Network grant both survive an
+  UPGRADE install. Android's intent extra prevents the menu's
+  automatic launch; versions with expo/expo#49651 also honor
+  the session-only FAB flag in Stim's deep link.
+  The phone's unverified remedy is also ROUTED, not a fixed
+  list. When this launch's device records carry the Local
+  Network path reason, the remedy leads with that evidence and
+  with \`agent-device alert get\`, \`alert accept\`, then
+  \`snapshot -i\` and \`press 'label="Reload"'\` -- the grant
+  alone does not reload the dev client. Otherwise the network
+  list stays. Routing changes no record's level, so nothing new
+  reaches \`logs --errors\`. The OTHER first-launch tap,
+  developer trust, has no API at all and is always the user's.
+  \`guide errors unverified\` has the signature and the
+  full commands.`
+			},
+			stats: {
+				summary: "the stats payload, what counts as a run, hit, miss and failed, timeSavedMs, the heartbeat estimate",
+				body: () => `  stim stats --json
+
+  { "version": 1,
+    "project": { "key": "<path>", "ios": <bucket|null>,
+                 "android": <bucket|null> } | null,
+    "machine": { "ios": <bucket|null>, "android": <bucket|null> } }
+
+  \`project\` is null outside a project; a platform with no run yet is null.
+  A bucket carries runs, failed, hits, misses, coldRuns, coldRunMs, hitRuns,
+  hitRunMs, timeSavedMs, firstRunAt and lastRunAt, plus lastColdBuildMs and
+  lastPodsMs once the project has compiled or installed pods. Milliseconds are
+  integers.
+
+HOW A RUN IS COUNTED (\`stats\`)
+  Every \`ios\` or \`android\` invocation that got as far as computing a
+  cache key is one run, in this project's bucket and in the machine-wide one.
+  The project key is the app's path IN THE SOURCE CHECKOUT, so every
+  worktree of a repository pools into one bucket and two apps in a monorepo
+  do not. A run that ends through an error or an uncaught exception counts
+  only as \`failed\`; \`launched: "unverified"\` or \`"bundling"\` is a
+  success. Otherwise the run's own \`cacheHit\` decides: "local" or "remote"
+  is a HIT, false is a MISS -- including a release run on a phone and a swap
+  that fell back to a full build. A miss adds its \`durationMs\` to the cold
+  runs; a hit adds it to the hit runs and credits \`timeSavedMs\` with this
+  project's mean cold run BEFORE it, minus its own duration, floored at zero.
+  A hit that WAITED for another workspace's build (\`waitedForBuild\`) counts
+  as a hit and is credited nothing: the compile it skipped was paid for in the
+  wait, and with no cold run recorded for this project and platform there is
+  nothing to compare against, so it credits nothing either. The saved figure
+  is therefore an ESTIMATE and is printed as one. Nothing per run is stored;
+  the file is $STIM_HOME/stats.json (see \`guide lifecycle builds\`).
+
+  A run also keeps the duration of its own two long phases in that bucket:
+  the build phase of a miss that compiled (lastColdBuildMs) and the last
+  \`pod install\` (lastPodsMs). The last value only, not a series. THAT IS
+  WHERE THE HEARTBEAT ESTIMATE COMES FROM. A later run reads this project's
+  bucket before it compiles, and prints:
+
+    build       still compiling (1m00s of ~3m10s)
+    pods        still installing (1m30s of ~1m40s)
+
+  The \`~\` value is THIS PROJECT'S LAST COLD BUILD, or its last
+  \`pod install\`, and never a mean: a project's build time drifts with its
+  size, so the most recent run is the best single guess. Past the estimate
+  the line reads \`(4m00s, usually ~3m10s)\`, because a slower machine is not
+  a hang. A project with no record yet gets \`(1m00s)\`, the elapsed alone,
+  and a warm run has no long phase to size. That read takes no lock and
+  ignores what it cannot read, so nothing about statistics can change a
+  run's outcome.`
+			}
+		}
+	},
+	metro: {
+		summary: "The dev server: `stim start`, the supervisor, and starting your own",
+		body: () => `THE DEV SERVER
+
+  stim start
+  stim start --remote   # prepare Metro for a remote device
+
+Reserves (or reuses) this workspace's Metro port, starts the dev server under a
+detached SUPERVISOR, and waits until it both answers AND verifies as this
+project's before exiting. You get your shell back with a bundler running: no
+backgrounding idiom, no sleep, no poll loop, and no chance of building against
+another worktree's bundler.
+
+  --json            one line of facts on stdout, everything else on stderr:
+                      { port, supervisorPid, mode, logsDir, alreadyRunning }
+  --wait <seconds>  how long to wait for server and remote tunnel readiness
+                    (default 60 for each)
+  --remote          expose Metro for a remote device
+
+Plain \`stim start\` is local and does not create a public tunnel. Remote intent
+comes from \`start --remote\`, \`ios.remote\`, or \`android.remote\`. The
+\`metro.tunnel\` setting selects the provider after remote intent exists.
+
+REMOTE DEVICE BACKENDS
+  Metro exposure and device selection are separate:
+
+    stim start --remote          prepare public Metro
+    stim ios --remote proxy      use an agent-device daemon
+    stim android --remote eas    create an EAS Simulator session
+
+  The command or the matching ios.remote/android.remote setting selects the
+  backend. Environment variables never select the backend.
+
+  The proxy backend connects to an agent-device daemon on another machine. It
+  requires AGENT_DEVICE_DAEMON_BASE_URL and
+  AGENT_DEVICE_DAEMON_AUTH_TOKEN. Stim creates no remote session for it.
+
+  The EAS backend needs eas-cli and an account with EAS Simulator access. An
+  EAS session is billable. EAS does not inherit the proxy credentials. Always
+  tear the session down: \`stop\`, \`worktree remove\`, and \`gc --delete\`
+  can end sessions that Stim proves it owns.
+
+IDEMPOTENT
+  A healthy dev server on the reserved port is a no-op: \`start\` prints the
+  facts with alreadyRunning: true and starts nothing. A foreign process holding
+  the reserved port moves the RESERVATION instead, so the project is never
+  stranded on a port it can never use.
+
+WHAT THE SUPERVISOR IS
+  One detached process per workspace. There is no machine-wide daemon, nothing
+  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:
+
+    bare-inproc  bare React Native: Metro is hosted INSIDE the supervisor,
+                 from the project's own node_modules, with Stim's reporter
+                 attached. Bundler events, in-app console logs and redboxes
+                 all arrive structured.
+    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.
+
+  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
+  locked to port 8081, which every reserved port but the first collides with)
+  and records the URL Expo reports under state.json's metroTunnel. This has to
+  happen here: \`ios --remote <proxy|eas>\` / \`android --remote <proxy|eas>\`
+  cannot add \`--tunnel\` to
+  an already-running dev server. A later \`start --remote\` refuses with a
+  stop-and-restart remedy when a healthy local Expo supervisor has no recorded
+  Expo tunnel. See \`guide settings\` for metro.tunnel.
+
+  \`stim status\` reports the pid, the mode, and whether it is answering.
+  \`stim stop\` is the inverse of \`start\`: it halts the supervisor, reaps
+  the device-log collectors, shuts the owned device down (never deletes it)
+  and frees the port.
+
+  ENVIRONMENT: the supervisor -- and through it the dev server, including a
+  metro.config.js evaluated inside the expo child -- inherits the environment
+  of the \`start\` call that SPAWNED it. A later \`start\` that finds a healthy
+  supervisor is a no-op and cannot change a running supervisor's env: to apply
+  a new env var, \`stop\` first, then \`start\` with it set.
+
+  The supervisor's own stdio goes to the global workspace logs/supervisor.log, which is NOT
+  part of the NDJSON timeline. It is what a supervisor that died before it
+  could write a structured record leaves behind. In expo-child mode the child's
+  output is parsed into the TIMELINE instead, so a dev server that dies on a
+  config error leaves supervisor.log empty and its death cry in metro.ndjson.
+  A failed \`start\` quotes both for you: the supervisor.log tail when it has
+  one, and this attempt's error records from the timeline.
+
+STARTING YOUR OWN BUNDLER STILL WORKS
+  A dev server YOU started is detected and left alone: \`start\` reports it
+  with supervisorPid: null and mode: null, exits 0, and starts nothing over it.
+  Starting a second bundler on a working one is the actual failure. For
+  \`start --remote\`, an external Expo server also needs metro.publicUrl because
+  Stim cannot add Expo tunnel mode to a process it does not supervise.
+
+  Start it from INSIDE the project directory, on the reserved port, or nothing
+  can attribute it to you:
+
+    Expo                      npx expo start --port <port>
+    Bare React Native         npx react-native start --port <port>
+    Has its own start script  run it and append --port <port>; it may carry
+                              flags that matter (e.g. --client-logs)
+    Monorepo                  run from the APP directory, not the repo root
+
+  The reserved port comes from \`stim status\` or from a previous
+  \`start --json\`. Then \`stim ios\` accepts it: its Metro gate checks that
+  the process on the port answers /status AND runs from inside this project,
+  and yours does.
+
+  The cost is logs. Stim captures only a dev server it hosted, so
+  \`stim logs\` stays empty -- which is indistinguishable from a clean run --
+  and finding output is back to redirecting it to a file yourself. Prefer
+  \`start\`.
+
+  \`stop\` leaves an externally started server running. Stop it with the tool
+  that started it.`
+	},
+	logs: {
+		summary: "Querying the merged NDJSON timeline, and what --errors means",
+		body: () => `LOGS
+
+  stim logs [filters]
+
+Reads every *.ndjson file in the global workspace logs directory, merges them into one timeline
+ordered by timestamp, prints what matches, and EXITS. The file set is
+discovered, not enumerated.
+
+EXIT 0 MEANS THE QUERY SUCCEEDED, whether or not records matched. A clean
+\`stim logs --errors\` check requires exit code 0 AND no matching errors in
+captured logs. An empty result does not prove launch or log capture succeeded;
+a workspace with no log directory also returns an empty result.
+
+For zero matches: STDOUT IS EMPTY, exit code 0, and
+one dim note on STDERR reading \`No matching log records in <logs dir>\`
+(human mode only -- \`--json\` prints nothing at all, on either stream).
+The only exit-1 paths are a malformed query and no project.
+
+FLAGS
+  --source <s...>  metro, client, device, build (one or more), or all. An
+                   unknown value is REJECTED rather than quietly matching
+                   nothing.
+  --level <l>      minimum level: debug, info, warn, error, fatal
+  --since <d>      only records newer than this: 30s, 5m, 2h
+  --grep <re>      only records whose msg matches this regular expression
+  --tail <n>       only the last n MATCHING records (applied after filtering,
+                   so --level error --tail 5 is the last five ERRORS)
+  --errors         errors and fatals since the last marker, from metro, client
+                   and build, plus confirmed native app-crash reports.
+                   Capped at 20 printed records.
+  --follow         keep streaming until interrupted (Ctrl+C is exit 0)
+  --json           the raw records, one per line, so stdout is valid NDJSON.
+                   ZERO matches is ZERO bytes on stdout (an empty NDJSON
+                   stream), exit 0 -- parse stdout line by line, never as one
+                   JSON document. The "No matching log records" note is human
+                   mode only, on stderr.
+
+--ERRORS, PRECISELY
+  Level error or fatal, from metro, client and build, plus device records with
+  event native_crash (app/device/time-correlated OS reports or fatal app console output), timestamped after the
+  marker that closes their window. Three rules, and a field test
+  caught all three wrong at once -- it returned 3,004 iOS syslog lines on a
+  healthy app while hiding a real startup crash.
+
+  SCOPE. General device logs are NOT in the default scope. A device log is the OS talking:
+  \`simctl log stream\` is predicated on the app's PROCESS, and inside that
+  process Apple's frameworks log thousands of Error-typed lines (nw_socket,
+  SecTrust, WebKit, CoreUI) that have nothing to do with your app. The proven
+  ones are demoted to info by the collector; the scope rule covers the rest.
+  The metro stream carries exactly one demotion of its own, and it is Stim's
+  doing: the dev-client deep link \`ios\`/\`android\` open to wire the app to
+  your port arrives inside the app as a link, and React Navigation logs at
+  error that no navigator handled a NAVIGATE to \`expo-development-client\`.
+  There is no such screen and there is not meant to be, so that one record is
+  recorded at info -- it made every healthy cold launch report 1 error. A real
+  unhandled NAVIGATE names a route your app has, and is still an error.
+  A native crash can happen before JS or Metro exists. Confirmed native_crash
+  records are included without admitting the rest of the device noise. Opt back in with
+  \`--source device\` or \`--source all\`; a plain \`logs\` with no --errors
+  has always shown everything. ON A PHYSICAL IPHONE opting back in buys less
+  than it does on a simulator: the device console carries no severity, so
+  \`--source device --errors\` there reports crash and refusal lines only,
+  never a level. Read a phone's device records with a plain \`logs
+  --source device\`.
+
+  THE WINDOW. A marker closes the window for the sources it can speak for:
+    a BUNDLE marker (src metro: bundle_build_done / bundle_build_failed, or
+      Expo's "Bundled" / "Bundling failed" lines) is written when a bundle
+      attempt FINISHES, success or failure. It resets METRO errors from
+      before the attempt -- a resolve failure you fixed and rebuilt is
+      history, and when bundles fail back to back only the newest attempt's
+      errors are reported -- and nothing else. A failed attempt's own summary
+      and details land at or after its marker, so they stay reported.
+    a LAUNCH marker (src build, written before \`ios\` / \`android\` attempts
+      launch) resets EVERYTHING. It precedes the tool call so an immediate
+      native crash is not hidden by a marker written after the process died.
+  A finished bundle is not evidence that the app which loaded it is fine.
+  In the field case the app threw at 16:03:54 and Metro wrote its marker at
+  16:03:55, one second later, because the bundler finishes accounting for a
+  build after the client has already evaluated it. Under one marker for all
+  sources that crash was reported as nothing at all. The cost of the rule is
+  the safe direction: a client redbox that Fast Refresh already fixed keeps
+  being reported until the next launch.
+
+  OUTPUT. Every logs command, including --errors and --follow, shows full captured
+  error, component and native stacks, with no frame or message-length limit.
+  --errors shows the first 20 matching error records, plus stack context.
+  This record-count limit never truncates a stack. A footer reports hidden
+  records; use its printed --tail value to include all records before grouping.
+  To read the complete timeline without the default error-record limit:
+    stim logs --source all
+  This includes all sources, levels and history, not just the latest errors;
+  add --since, --level or --grep to narrow it. --source all selects sources,
+  not stack depth. For untouched captured records use:
+    stim logs --source all --json
+  Neither form can restore text the runtime truncated before capture.
+  In non-follow human output, an Expo error includes its immediately
+  following code frame and Call Stack lines. Bare React Native symbolication is
+  shown as separate context because Metro does not provide an error correlation
+  identifier. Context does not change the error count or the raw error records
+  returned by --json. --json is never capped, and neither is an explicit --tail.
+
+  In --follow mode the marker window is dropped -- every error arriving from
+  then on is by definition after the last marker seen.
+
+  \`stim status\` reports the same count per workspace, as
+  logs.errorsSinceMarker: the same query, the same scope, so the two can never
+  disagree about whether this workspace is failing.
+
+THE RECORD
+  { ts, src, level, msg } always. ts is epoch milliseconds; src is one of
+  metro / client / device / build; level is one of the five above.
+  Optional fields:
+    event    the producer's own event name (bundle_build_done, client_log, ...)
+    stack    frames of { file, line, column, fn }, passed through as reported
+    marker   true on the records that close an error window
+    deviceTs Android logcat's original epoch milliseconds; ts is aligned to
+             host time using a bounded clock query at each collector attachment
+    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)
+
+WHAT WRITES WHAT
+  metro.ndjson         the bundler, in both supervisor modes
+  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.
+  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
+                       before launch; Android attaches once the pid is known
+                       and reads buffered logcat records. This
+                       is where a native crash that never reached JS shows up
+                       -- and, on iOS, where every Apple framework running in
+                       the app's process also logs. The proven noise sources
+                       are recorded at info rather than error; the rest is why
+                       --errors leaves this source out unless asked. A VERIFIED
+                       LAUNCH counts these records and prints one line:
+
+                         launch      9 general device error-level records
+                                     (not confirmed app errors); inspect with
+                                     stim logs --errors --source device
+
+                       The count does not attribute unknown OS errors to the app.
+                       Known JavaScript errors also print individually: Android
+                       ReactNativeJS records, and iOS com.facebook.react.log /
+                       javascript records. These can interrupt an optional
+                       readiness wait even without a client or Metro copy.
+                       Client and Metro errors still print individually.
+                       A native app that loaded its bundle but reported app errors
+                       ends with WARNING rather than OK. This does not change the
+                       launch JSON or exit code: launched describes bundle/process
+                       evidence, not a healthy UI. Inspect the errors and readiness.
+
+                       Only human ios/android launch output previews up to
+                       ten frames per error, component or native stack. App-source
+                       frames take priority; selected frames retain captured
+                       order, with an omitted-frame count. Escaped
+                       component stacks print one frame per line. Long bundle
+                       URLs are shortened and labeled unsymbolicated; shortening
+                       is not source-map resolution. A Metro error body that an
+                       Android DebugServerException embeds prints as the
+                       error's message and import stack, not its JSON. All
+                       logs commands show full
+                       captured stacks, including \`stim logs --errors\`.
+                       Use \`stim logs --source all\` for all sources/history,
+                       or add \`--json\` for raw
+                       records. This preview does not alter logs or JSON.
+
+                       Symbolication is best effort. Human launch and non-follow
+                       logs queries ask the verified workspace Metro's /symbolicate
+                       endpoint to resolve captured JS coordinates, with a 2s
+                       request deadline and raw-coordinate fallback. Successful
+                       launch context is retained separately under logs/error-context
+                       so stopping Metro does not discard resolved evidence.
+                       Expo code frames are attached; uncorrelated bare Metro
+                       symbolication events remain separate. A component stack
+                       never substitutes for a missing error stack. Historical
+                       stacks need matching sources/maps, not a rebuilt bundle.
+
+                       Cross-source copies combine only with matching error
+                       title, stack location, compatible platform and timing.
+                       Same-source repeats and raw JSON records stay intact.
+                       Human queries may attach a correlated device component
+                       stack to a selected Metro error, but never an unrelated
+                       device error.
+
+                       iOS simulator cold launch attaches app stdout/stderr and
+                       passes Expo's initial URL directly. Fatal output is available
+                       before delayed OS reports, which can take about a minute
+                       or longer to appear; rerun logs --errors for those
+                       before stopping or releasing the device. Collection requires
+                       this workspace's current launch and device ownership or lease;
+                       afterward only already-captured reports remain available.
+                       The app cache holds console files, so external STIM_HOME
+                       paths do not violate the app sandbox. Crash evidence is
+                       retained in workspace logs. --follow does not poll for
+                       delayed OS reports.
+                       Native iOS simulator reports match app ID, simulator ID
+                       and launch time. atos resolves app addresses only after
+                       the local binary UUID matches the report. Android reads
+                       the crash buffer even when the app PID has exited. Java
+                       traces remain readable; C/C++ resolution uses NDK tools
+                       and matching local ELF build IDs. General OS noise remains
+                       excluded from --errors. Full native evidence is in
+                       logs --source device --json. Physical iPhone capture stays
+                       console-only; missing reports or symbols are not proof
+                       of a healthy app. No symbol downloads are performed.
+                       Android may keep a crashed Java PID alive behind its
+                       crash dialog. Follow the app-scoped force-stop remedy
+                       printed by android after fixing the crash, then rerun
+                       stim android. Metro reload alone cannot recover it.
+
+                       The connection refusal \`TCP Conn ... Failed :
+                       error 0:61 [61]\` (61 is ECONNREFUSED) is not even
+                       counted. The app got its bundle over this workspace's
+                       Metro and outlived the stability window, so it
+                       recovered. A refusal before the
+                       launch verifies still prints, as does every record on a
+                       launch that does not verify, and the record stays an
+                       error in device.ndjson either way; read it with
+                       \`logs --errors --source device\`.
+
+  ON A PHYSICAL IPHONE THE SAME FILE CARRIES LESS, and the difference is not
+  cosmetic. \`simctl spawn\` is simulator-only and there is no devicectl
+  console subcommand, so a device run reads
+  \`devicectl device process launch --console\`, which connects the app's own
+  stdout and stderr and nothing else. Stim launches it with
+  OS_ACTIVITY_DT_MODE, which makes os_log mirror itself onto that stderr --
+  without it React Native's own logging, which goes through os_log, would not
+  appear at all. What the mirror carries, and what it drops:
+
+    ts        KEPT   the device's own timestamp, off the mirrored line
+    proc      KEPT   as name(pid), from the mirrored line, not a path
+    category  KEPT   only when the logger has a subsystem; \`javascript\` and
+                     \`native\` for React Native's own log calls
+    msg       KEPT   a multi-line message arrives as separate records
+    subsystem LOST   the mirror never prints it
+    level     LOST   Default, Error and Fault all render identically, and
+                     Debug is not mirrored at all
+
+  So every device record from a phone is \`raw: true\` and \`info\`, except
+  the lines that OPEN with a marker the runtime itself prints: an uncaught
+  ObjC exception, a libc++abi termination, an assertion failure, or a Swift
+  fatal error. The match is anchored, so an app logging ABOUT a crash stays
+  info. devicectl's own \`ERROR:\` is read only on a line with no mirror
+  prefix, because that is the only kind devicectl writes. Severity cannot be
+  recovered, so it is not guessed. The NOISE_RULES that demote Apple's framework chatter key on
+  subsystem and cannot fire either -- but they have less to do, because
+  --console carries only the app's streams rather than every framework
+  logging inside its process.
+
+  \`log collect --device-udid\` WOULD carry all six fields, in the same NDJSON
+  the simulator path parses. It is not used because it requires root
+  (\`log: Must be root to collect logs from attached device\`) and produces an
+  archive rather than a stream. Streaming with full fidelity needs
+  libimobiledevice or pymobiledevice3, which are third-party installs Stim
+  does not require. See appandflow/stim#179.
+  build-ios.ndjson     the xcodebuild / gradle transcript at level debug, the
+  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.
+
+  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
+  clean build. The device and build sources are written either way, because
+  \`ios\` / \`android\` produce them.
+
+  A collector is killed and replaced on the next \`ios\` / \`android\` run for
+  that platform, and reaped by \`stop\`.`
+	},
+	errors: {
+		summary: "Every refusal Stim can print: an index of codes, and one section for each",
+		sectionHint: "<CODE>",
+		preamble: () => `WHAT STIM REFUSES, AND WHY
+
+Every refusal from \`ios\` / \`android\` carries a stable CODE. Branch on the
+code, never on the message.`,
+		sections: {
+			STIM_WORKSPACE_STATE: {
+				summary: "$STIM_HOME/workspaces could not be prepared, or the digest directory belongs to another project",
+				aliases: ["STIM_WORKSPACE_COLLISION"],
+				separator: "--- BUILD-PATH CODES (`stim ios` / `stim android`) ---",
+				body: () => `STIM_WORKSPACE_STATE / STIM_WORKSPACE_COLLISION
+  Stim could not prepare this project's global workspace directory under
+  $STIM_HOME/workspaces. Check that STIM_HOME is writable and has free
+  space. An EPERM on a directory the user CAN write is a sandbox, not a
+  permission bit -- see \`stim guide errors sandbox\`. COLLISION means the
+  readable-name-plus-digest directory already has a workspace.json for a
+  different canonical project path; do not overwrite it until you identify
+  which workspace owns it.`
+			},
+			STIM_NO_METRO: {
+				summary: "nothing provably this workspace's dev server holds the reserved port (ios, android, reload)",
+				body: () => `STIM_NO_METRO
+  Nothing that could be proven to be THIS workspace's dev server holds the
+  reserved port -- or no port is reserved at all. The gate fires in about a
+  second, before the device is even booted, rather than after four minutes of
+  compiling an app that could not load a bundle. Run \`stim start\` first.
+  \`--no-metro-check\` overrides it and wires the app to the reservation (or to
+  8081 when there is none). A non-Debug \`ios --configuration\` never emits
+  this: a release-shaped build embeds its JS, so the gate does not run at all.
+  A port held by SOMETHING ELSE reports what: usually a bundler started from
+  the wrong directory (the repo root instead of the app dir in a monorepo), or
+  another repo's Metro. Restart it from inside the project, or free the port
+  and run \`stim start\` to get a fresh reservation.
+
+  Reload requires the recorded launch's port to be this workspace's live
+  Metro. It refuses a missing, changed, unresponsive, or foreign port.`
+			},
+			STIM_NO_FINGERPRINT: {
+				summary: "@expo/fingerprint produced no hash, so the shared cache cannot be addressed",
+				body: () => `STIM_NO_FINGERPRINT
+  \`@expo/fingerprint\` produced no hash, so the shared build cache cannot be
+  addressed. Stim uses its declared @expo/fingerprint dependency directly,
+  independently of the target project's package graph. This is a refusal
+  rather than a silent full build because an unaddressable cache means every
+  workspace on the commit compiles from scratch, forever.`
+			},
+			STIM_PREBUILD_FAILED: {
+				summary: "expo prebuild could not generate the native directory",
+				body: () => `STIM_PREBUILD_FAILED
+  \`expo prebuild\` could not generate the missing native directory. The
+  extracted output is above the code; the transcript is in
+  the global workspace logs/build-<platform>.ndjson file.`
+			},
+			STIM_DEPS_FAILED: {
+				summary: "pod install or gradle sync failed; the bundler ladder and BUNDLE_FROZEN",
+				body: () => `STIM_DEPS_FAILED
+  \`pod install\` (iOS) or the gradle dependency sync (Android) failed. On iOS
+  this runs only when Podfile.lock and Pods/Manifest.lock disagree, or Pods is
+  absent -- which is exactly what a carried worktree produces.
+  WHICH POD COMMAND: when the project root has a Gemfile and a Gemfile.lock
+  that resolves cocoapods, pods go through bundler -- \`bundle check --dry-run\`,
+  then \`bundle install\` only when that reports missing gems, then \`bundle exec
+  pod install\` -- so the CocoaPods the lockfile pins is the one that writes
+  Podfile.lock. Everything else gets plain \`pod install\`: no Gemfile, a Gemfile
+  with no Gemfile.lock (\`bundle install\` would CREATE that tracked file in
+  your checkout, which Stim will not do), and a Gemfile.lock that
+  pins something other than pods, such as a fastlane-only bundle. When
+  \`bundle\` is not on PATH the run prints one dim \`pods\` note and uses plain
+  \`pod install\`. The \`pods\` phase line always names the command that ran, and
+  the gem steps heartbeat under the \`gems\` label.
+  Bundler runs with BUNDLE_FROZEN, so a Gemfile that no longer matches its
+  Gemfile.lock FAILS the build rather than quietly falling back to unpinned
+  pods -- silently using a different CocoaPods than the lockfile pins is the
+  bug this path exists to kill. Run \`bundle install\` yourself and keep the
+  result. Gems themselves are installed wherever BUNDLE_PATH points -- the
+  project's own \`.bundle/config\` (vendor/bundle in the React Native template),
+  or the environment. When that lands inside the project, Stim says so in a dim
+  note naming which of the two set it; Gemfile.lock is never edited either way.
+  \`worktree warm --refresh\` reports the same code for the install it runs in
+  the SOURCE CHECKOUT -- the lockfile's own command (\`pnpm install\`,
+  \`yarn install\`, \`bun install\`, \`npm ci\`) or that same pod ladder. The
+  message names the command, quotes its last lines, and nothing is copied: fix
+  the source checkout, then warm again.`
+			},
+			STIM_BUILD_FAILED: {
+				summary: "xcodebuild or gradle failed; the two Android APK refusals; a damaged compilation-cache object",
+				body: () => `STIM_BUILD_FAILED
+  xcodebuild or gradle failed. The EXTRACTED diagnostics are printed (capped),
+  not the transcript. Read the log path on the next line for the rest.
+  Two Android refusals share this code without gradle itself failing:
+  - MORE THAN ONE debug APK under android/app/build/outputs/apk and nothing
+    configured to pick one (a project with product flavors, several flavors
+    already built). Stim will not guess which flavor to install: the
+    refusal lists the candidates -- pass \`--variant <name>\` or set the
+    android.variant setting (e.g. "productionDebug") to the one you want.
+    Flavors declared plainly in android/app/build.gradle are caught before
+    the build instead (STIM_BAD_ARG); this one remains for the declarations
+    that parse cannot read.
+  - NO APK for the configured variant: the android.variant / --variant value
+    does not name a real variant (\`./gradlew :app:tasks\` in android/ lists
+    the assemble tasks).
+  AN APK OLDER THAN THE BUILD IS NOT A REFUSAL. \`assembleDebug\` packages every
+  flavor, so a later \`--variant previewDebug\` finds a current APK that gradle
+  reports UP-TO-DATE and repackages nothing. Stim installs it. Gradle owns task
+  freshness and the fingerprint owns cache freshness; Stim does not second-guess
+  either from the file's mtime.
+
+"failed to scan dependencies for source ..." on pods you did not touch  (ios)
+  The compilation cache holds a damaged object. Xcode reports it per source
+  file, so it names whichever targets reach the object first -- often pods such
+  as sqlite3, nanopb or libwebp -- and the list changes between runs. The
+  transcript carries the cause:
+    error: CAS-based dependency scan failed: not a IncludeTreeRoot node kind
+  A cache write that a full disk or a killed build cut short leaves such an
+  object, and upgrading the CLI does not clear it. Empty that one cache with
+  \`gc --delete --cache "compilation cache"\`, then build again. The next
+  build is a cold one.`
+			},
+			fallbacks: {
+				summary: "release cache-hit notes that are not codes: swap failure, asset gate, uninstall, device fallbacks",
+				body: () => `FALLBACK NOTES THAT ARE NOT CODES (release cache hits)
+  On a release cache hit Stim regenerates this workspace's JS bundle into a
+  COPY of the cached artifact before installing it -- \`ios --configuration
+  Release\` into a copy of the .app, \`android --variant ...Release\` into a
+  copy of the APK. When any step of that swap fails (the bundle command,
+  hermesc, the re-sign, zipalign, apksigner), the run does NOT install the
+  cached artifact -- its baked-in JS is the builder's, not yours -- and does
+  NOT fail: it prints a \`swap        failed at <step>: ... --
+  building fresh instead\` note on stderr and falls back to a full build. If
+  the run then fails, the code is the build's own (STIM_BUILD_FAILED etc.);
+  the swap note above it says why the cache hit was not used. A swap that
+  merely finds no hermesc notes it and embeds the plain JS bundle instead --
+  that is a note, not a fallback.
+
+  ANDROID'S ASSET GATE is the second, and it is not a failure at all. Before
+  re-packing, Stim compares this workspace's freshly emitted asset tree
+  against the assets the cached APK carries. Any added, removed or changed
+  asset prints
+
+    swap        this workspace's asset set differs from the cached APK's
+                (1 added, 0 changed, 0 removed; e.g. added
+                res/drawable-mdpi/new_logo.png) -- building fresh instead
+
+  and the run does a full gradle build. There is nothing to fix: a drawable
+  has a row in resources.arsc that only AAPT can write, so an APK cannot be
+  made to carry an asset it was not built with, and installing one whose JS
+  references a missing asset would 404 at runtime. Add an image, pay for one
+  full build; the APK it produces becomes the new cache entry.
+
+  THE UNINSTALL NOTE is the third, and it COSTS THE APP'S DATA. A re-packed
+  APK is signed with this machine's debug keystore, so the moment it meets a
+  copy signed by CI the install is refused with
+  INSTALL_FAILED_UPDATE_INCOMPATIBLE (or INSTALL_FAILED_VERSION_DOWNGRADE) and
+  nothing but removing the package resolves it. A RELEASE run therefore
+  uninstalls the package once, retries the install once, and prints
+
+    install     com.example.app was already installed with a different signer,
+                so it was uninstalled (its data went with it) before this APK
+                could be installed
+
+  Debug runs never do this. A debug run meets the conflict on a physical
+  device that already carries a store build, and there the colliding package is
+  the user's real app: losing its data to a silent uninstall would be a worse
+  bug than the one it fixes. A debug run fails with STIM_INSTALL_FAILED and
+  hands you the uninstall to run yourself.
+
+  ON A PHONE the same uninstall costs one thing more: iOS drops the Settings >
+  General > VPN & Device Management trust entry when the last app from that
+  developer goes, and it clears the app's Local Network permission with it. The
+  note says so, because the reinstall succeeds and then the LAUNCH is refused
+  until someone taps Trust again. The retry is one uninstall and one install --
+  it is not a way around a tap that has no API.
+
+  THE DEVICE FALLBACKS are the fourth, and both print a \`cache\` note and
+  build fresh rather than failing:
+
+    cache       a cached Release device app carries its builder's JS, and the
+                device JS swap lands with phase 6 of appandflow/stim#178 --
+                building fresh instead, which bakes in this workspace's JS
+
+  and a signing-gate refusal on a CACHED artifact -- an expired or foreign
+  profile, a phone the profile does not name, an identity this keychain does not
+  hold -- which prints the gate's own reason with \`-- building fresh instead\`.
+  The same refusal on a FRESHLY BUILT app is a code (STIM_NO_PROFILE,
+  STIM_PROFILE_MISMATCH, STIM_NO_SIGNING_IDENTITY), not a note: building again
+  would produce the same app and refuse again.`
+			},
+			STIM_BUILD_WAIT_TIMEOUT: {
+				summary: "waited ~90 minutes for another workspace's build of the same fingerprint",
+				body: () => `STIM_BUILD_WAIT_TIMEOUT
+  This run was waiting for ANOTHER workspace's build of the same fingerprint
+  (see \`guide lifecycle concurrency\`), and no artifact arrived within ~90
+  minutes.
+  Replacement builders share that deadline, including time spent acquiring
+  the lock between waits. A live builder may be wedged, or successive builders
+  may have failed. The message names the current pid and lock directory:
+  check the pid, and if it is not really building, remove that directory and
+  run the command again.`
+			},
+			STIM_CLAIM_REFUSED: {
+				summary: "a build lock exists whose holder cannot be identified; Stim neither removes it nor waits on it",
+				body: () => `STIM_CLAIM_REFUSED
+  A build lock records the holder's process IDENTITY, not just its pid, so a
+  recycled pid reads as a gone builder rather than a live one, and a builder
+  busy in a long \`simctl\` or gradle call reads as live rather than as stale.
+  This code is the one state that cannot be decided: the claim file is truncated
+  or not JSON, its identity token does not decode, or the holder spawned the
+  process doing the work and was killed before recording which one.
+  Stim will not remove a claim it cannot prove is dead, and it will not wait on
+  one either -- a silent wait on a lock nobody holds is what this replaces. The
+  message names the claim and the exact, shell-quoted removal that clears it --
+  just that claim's file, not the lock directory around it; run that, then
+  run the command again. Nothing was built, installed or removed.
+  \`worktree warm\` reports it for the repository-wide warm claim under
+  ~/.stim/warm-locks on both paths, including a \`--refresh\` that spawned its
+  install and was killed before recording which process: nothing was refreshed
+  and nothing was copied. One case is NOT this code for a plain warm: a
+  STIM_HOME (or a warm-locks path under it) that is a file rather than a
+  directory. No claim can be stored there at all, which is a filesystem state
+  that predates claims, so plain \`warm\` degrades to the unsynchronised copy it
+  performed before them and \`--refresh\` still refuses.`
+			},
+			STIM_CLAIM_UNAVAILABLE: {
+				summary: "this process has no recordable identity, so no build lock or build slot can be taken at all",
+				body: () => `STIM_CLAIM_UNAVAILABLE
+  Every ownership claim records the holder's process identity, captured through
+  the \`unique-pid\` native module. This code is that capture failing: no
+  prebuilt binary for this platform and architecture, or the OS refusing to
+  report this process's start identity.
+  Stim refuses rather than building without a claim. A run with no claim is
+  invisible to every other run, so the single-flight lock and
+  concurrency.maxBuilds would both be off at once, and two builds could compile
+  the same fingerprint while each believed it was alone. Reinstall Stim so the
+  module for this platform is present, then run the command again. Nothing was
+  built, installed or removed.
+  \`worktree warm --refresh\` refuses for the same reason, because it writes to
+  the source checkout. Plain \`worktree warm\` does NOT: it prints one dim
+  \`lock        unavailable (...)\` line and copies unsynchronised. A copy only
+  reads, so running it with no claim is what it did before the lock existed,
+  while refusing it would break a warm that works today -- an unwritable
+  STIM_HOME included.
+  It still reads the claim set first, which takes no claim: a live \`--refresh\`
+  claim, or a claim it cannot resolve, makes even the unsynchronised copy
+  refuse, and the line names what it found. Only a repository nothing is
+  warming is copied without a claim.`
+			},
+			STIM_INSTALL_FAILED: {
+				summary: "simctl, adb, or devicectl refused the artifact; the one signer-conflict retry",
+				body: () => `STIM_INSTALL_FAILED
+  The artifact built or came from cache, but \`simctl install\` / \`adb install\` /
+  \`devicectl device install app\` refused it. A signature or architecture
+  mismatch, or a full device.
+  On a PHONE (\`ios --device\`) the message carries devicectl's own text and the
+  remedy names the cause it recognises: the phone is locked, the host is not
+  trusted, Developer Mode is off, storage is full, or the app already on the
+  phone was signed by a different team. Only that last one is retried -- one
+  \`devicectl device uninstall app\`, one reinstall, and a warning that the
+  app's data went with it -- along with the phone's developer trust and its
+  Local Network permission, which iOS clears on an uninstall, so the launch
+  after it may need the trust tap again. This is gated on \`--device\` rather
+  than on the configuration, because every device run is signed, Debug
+  included.
+  On Android a signature or downgrade conflict names the package that is really
+  installed -- the built APK's applicationId, which on a flavored project is
+  the flavor's id and not the gradle namespace -- and gives you the
+  \`adb -s <serial> uninstall <applicationId>\` that clears it. Re-running after
+  that is a cache hit: one install, no build.`
+			},
+			STIM_LAUNCH_FAILED: {
+				summary: "installed but would not start; the developer-trust tap on a phone",
+				body: () => `STIM_LAUNCH_FAILED
+  Installed, but the app would not start. On Android this usually means no
+  launchable activity resolved.
+  On a PHONE it means the app never appeared in the device's own process list
+  after \`devicectl device process launch\`, and the devicectl lines that
+  explain it are quoted under the message. The refusal a first launch usually
+  hits is the DEVELOPER TRUST one -- SpringBoard reports
+  FBSOpenApplicationErrorDomain 3 with the reason Security -- and its remedy is
+  the only one a human has to perform on the phone: Settings > General >
+  VPN & Device Management, tap the developer profile under DEVELOPER APP, tap
+  Trust, then run the command again. It is a per-developer-certificate tap, not
+  a per-build one -- but an uninstall clears it, including the one Stim's own
+  signer-conflict retry performs.`
+			},
+			STIM_NO_SCHEME: {
+				summary: "Xcode schemes unavailable or no unambiguous app scheme in ios/",
+				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.
+  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.`
+			},
+			STIM_NO_PROFILE: {
+				summary: "no or undecodable embedded.mobileprovision; build once from Xcode",
+				separator: "--- iOS SIGNING CODES (`ios --device`, and only there) ---",
+				context: `A simulator build needs no signature, which is why none of these can fire on
+the normal path. A device build carries one, and Stim re-seals any bundle it
+modifies with the identity the bundle already names -- so it checks, before
+spending a build or a bundle, that the check can succeed.`,
+				body: () => `STIM_NO_PROFILE
+  The built or cached .app has no embedded.mobileprovision, or
+  \`security cms -D\` could not decode the one it has. The first means the build
+  produced an unsigned app -- almost always a simulator-sliced artifact.
+  Set a team and a Development profile for the target's configuration in
+  Xcode > Signing & Capabilities, then BUILD ONCE FROM XCODE to install the
+  profile. Stim will not do that step: registering a device or minting a
+  profile changes your Apple Developer account, so Stim never passes
+  -allowProvisioningUpdates.`
+			},
+			STIM_PROFILE_MISMATCH: {
+				summary: "the profile is expired, has no ProvisionedDevices, or does not name this UDID",
+				context: `A simulator build needs no signature, which is why none of these can fire on
+the normal path. A device build carries one, and Stim re-seals any bundle it
+modifies with the identity the bundle already names -- so it checks, before
+spending a build or a bundle, that the check can succeed.`,
+				body: () => `STIM_PROFILE_MISMATCH
+  The profile inside the app cannot admit this phone. Three shapes, and the
+  message names which one and the profile type it found:
+    - it expired, or carries no ExpirationDate at all;
+    - it is an App Store or enterprise profile, which carries no
+      ProvisionedDevices list -- so Stim cannot PROVE the phone is admitted and
+      refuses rather than guessing. Local device runs need a development
+      profile;
+    - it is a development or ad hoc profile whose device list does not name
+      this UDID. Register the UDID at developer.apple.com, regenerate the
+      profile, and build once from Xcode.`
+			},
+			STIM_NO_SIGNING_IDENTITY: {
+				summary: "no single keychain identity resolves; ios.signingIdentitySha1 for two certificates",
+				context: `A simulator build needs no signature, which is why none of these can fire on
+the normal path. A device build carries one, and Stim re-seals any bundle it
+modifies with the identity the bundle already names -- so it checks, before
+spending a build or a bundle, that the check can succeed.`,
+				body: () => `STIM_NO_SIGNING_IDENTITY
+  No single keychain identity could be resolved to re-seal with. Either
+  \`security find-identity -v -p codesigning\` lists nothing, or the identity
+  the artifact's own profile names is absent, or two certificates share that
+  common name and Stim -- being non-interactive -- will not pick one.
+  Open Xcode > Settings > Accounts and download your certificates, or unlock
+  the login keychain with \`security unlock-keychain\`. For the two-certificate
+  case, set ios.signingIdentitySha1 to the SHA-1 hash beside the one you want.`
+			},
+			STIM_CODESIGN_FAILED: {
+				summary: "codesign failed on the modified copy; the cache entry is untouched and the run builds fresh",
+				context: `A simulator build needs no signature, which is why none of these can fire on
+the normal path. A device build carries one, and Stim re-seals any bundle it
+modifies with the identity the bundle already names -- so it checks, before
+spending a build or a bundle, that the check can succeed.`,
+				body: () => `STIM_CODESIGN_FAILED
+  \`codesign --force --sign\` or \`codesign --verify --strict\` exited non-zero
+  on the modified copy. The verbatim codesign stderr is quoted, because it is
+  the answer: a locked login keychain reports errSecInternalComponent, an
+  ambiguous identity reports that it matched more than one. Unlock the keychain
+  and confirm exactly one identity matches the name. The cache entry itself is
+  never modified -- the failure is on a temporary copy, and the run builds
+  fresh.`
+			},
+			STIM_NO_LAN_ADDRESS: {
+				summary: "the Mac has no non-internal IPv4 interface; a tunnel cannot help a phone",
+				separator: "--- iOS DEVICE DEBUG REACHABILITY CODES (`ios --device` in Debug) ---",
+				context: `A phone does not share the host's loopback and USB carries no reverse forward,
+so a Debug run on one is wired to a LAN origin instead of localhost. Both codes
+fire BEFORE the build, because a refusal that costs a build is a bad refusal.`,
+				body: () => `STIM_NO_LAN_ADDRESS
+  This Mac reports no non-internal IPv4 interface, so there is no address to
+  give the phone: it is offline, or on nothing but utun/awdl/bridge. Join a
+  Wi-Fi or Ethernet network, or connect this Mac by cable, and run again.
+  Deliberately NOT "set metro.publicUrl": neither channel to a phone carries a
+  URL. The dev-client deep link composes http://<host>:<port> itself, and
+  ip.txt is read by RCTBundleURLProvider, which prefixes the scheme. A tunnel
+  cannot be expressed to a phone, so --device ignores metro.publicUrl,
+  metro.tunnel and metro.ngrokUrl and says so when one is set.`
+			},
+			STIM_LAN_METRO_UNREACHABLE: {
+				summary: "the LAN origin did not answer as this workspace's Metro; ios.lanHost on a multi-NIC Mac",
+				context: `A phone does not share the host's loopback and USB carries no reverse forward,
+so a Debug run on one is wired to a LAN origin instead of localhost. Both codes
+fire BEFORE the build, because a refusal that costs a build is a bad refusal.`,
+				body: () => `STIM_LAN_METRO_UNREACHABLE
+  The chosen LAN origin did not answer as THIS workspace's Metro: no answer, a
+  5xx, or a dev server that is not this one -- the message says which.
+  \`stim start\` prints the port it reserved. On a Mac with several interfaces
+  the first en* is not necessarily the one the phone shares: set ios.lanHost to
+  the address it can reach (see \`guide settings\`).
+  What this gate CANNOT prove is that the phone can reach the origin: macOS
+  routes a host connection to its own address over loopback, so the gate passes
+  through a firewall that will block the phone. That evidence only ever arrives
+  from the phone's own bundle request, which is what \`launched\` reports.`
+			},
+			unverified: {
+				summary: "launched: \"unverified\" with the Local Network path reason, and the routed recovery",
+				context: `A phone does not share the host's loopback and USB carries no reverse forward,
+so a Debug run on one is wired to a LAN origin instead of localhost.`,
+				body: () => `LAUNCH UNVERIFIED, LOCAL NETWORK NOT GRANTED (not a code -- a routed remedy)
+  An app that has not been granted Local Network reaches nothing on the LAN,
+  and CFNetwork reports each attempt as NSURLErrorDomain -1009 "The Internet
+  connection appears to be offline." with the path reason
+
+    _NSURLErrorNWPathKey=unsatisfied (Local network prohibited)
+
+  THAT REASON IS THE WHOLE MATCH. The rest of the block -- POSIX error 50
+  (ENETDOWN), \`failed to connect 1:50\`, \`error code: -1009 [1:50]\` -- is
+  generic and says nothing about the permission: Wi-Fi turned off gives the
+  identical errno with the reason \`unsatisfied (No network route)\`, and a
+  cellular-only route gives \`unsatisfied (Denied over cellular interface)\`.
+  Matching those would print this remedy at a phone that simply is not on the
+  network, and would drop the same-SSID check that is the actual fix, so they
+  are not matched.
+  THE PROMPT AND A PRIOR DENIAL READ THE SAME. iOS emits this reason while the
+  prompt is unanswered and after a Don't Allow, which persists across upgrade
+  installs. The remedy covers both: if the first \`alert get\` finds no alert,
+  it was denied earlier and the only fix is the switch under Settings > Privacy
+  & Security > Local Network, which has no API.
+  The reason is read out of THIS launch's device records -- since the launch,
+  and from the app's pid when it is known. It is NOT origin-scoped: the record
+  that carries the reason carries no URL (the failing URL lands in a
+  continuation line with no process prefix, which the pid filter drops), so
+  scoping to this workspace's Metro origin would never fire. That is sound
+  anyway, because the permission gates every LAN connection the app makes, so
+  even a third-party SDK's prohibited connection proves the app cannot reach
+  this workspace's Metro either. Matching only picks the remedy: no record's
+  level changes, so the device source stays out of \`logs --errors\`
+  (\`guide logs\`: severity is never guessed on a phone).
+  When it matches, \`launched: "unverified"\` leads with that evidence and with
+  the recovery, in this order:
+
+    agent-device alert get --platform ios --udid <udid>
+    agent-device alert accept --platform ios --udid <udid>
+    agent-device snapshot -i --platform ios --udid <udid>
+    agent-device press 'label="Reload"' --platform ios --udid <udid>
+
+  \`alert get\` reads the alert without opening anything, so it works while the
+  app sits behind it. THE GRANT ALONE IS NOT ENOUGH: the dev client does not
+  retry, and stays on "Failed to load app ... The Internet connection appears
+  to be offline." with a Reload button, which is why the last two lines are
+  there. The text form of the press target is \`label="Reload"\` (or
+  \`text="Reload"\`); a bare \`press "Reload"\` is rejected. Stim's own launch
+  ends in \`-- -EXDevMenuShowsAtLaunch 0 -EXDevMenuShowFloatingActionButton 0\`,
+  so the Expo dev menu is not over the app, fresh install or not. An app started
+  ANOTHER way does not carry those arguments and \`snapshot -i\` can show the
+  menu instead: \`agent-device press 'label="Close"'\` dismisses it, then press
+  Reload. See \`guide facts devmenu\`.
+
+  A BARE APP (no expo-dev-client) gets the same first two commands and a
+  different third. The prompt fires the same way, because it is fired by any
+  LAN connection to the Metro host, and the path reason is CFNetwork's either
+  way -- the classifier reads that reason alone and knows nothing about dev
+  clients. What differs is the screen: a bare app is expected to show React
+  Native's RedBox, "Could not connect to development server". Read the screen
+  with \`agent-device snapshot -i\` and press Reload by the ref or label it
+  reports; neither that text nor the button's accessibility label has been read
+  off hardware.
+
+  \`agent-device metro reload\` does NOT recover either screen. It only reaches
+  an app already connected to Metro's websocket, and an app stopped by this
+  permission never connected.
+
+  Without agent-device,
+  \`xcrun devicectl device process launch --device <udid> --terminate-existing
+  [--payload-url '<devClientUrl>'] <bundleId>
+  [-- -EXDevMenuShowsAtLaunch 0 -EXDevMenuShowFloatingActionButton 0]\`
+  also recovers, and it costs the device log:
+  it replaces the process the collector follows, so
+  \`stim logs --source device\` stops for the rest of that run. For a dev
+  client, pressing Reload is cheaper and keeps the collector alive. For a bare
+  app the relaunch is the cleanest recovery, because it re-reads ip.txt. By
+  hand it is two taps either way: Allow, then Reload.
+
+  WHAT HAS ACTUALLY RUN: the dev-client path above was performed on a phone --
+  the alert, the accept, the unchanged error screen, the Reload press, and the
+  bundle that followed. The bare path has NOT been exercised on hardware; there
+  is no provisioned bare project to run it on. Its signature and its remedy are
+  reasoned from the same CFNetwork evidence and from React Native's own
+  RedBox, not observed.
+
+  THE OTHER ONE-TIME TAP HAS NO API. The developer-trust tap (Settings >
+  General > VPN & Device Management) is refused to automation by the same gate
+  that refuses the app, agent-device's own runner included, so its remedy is
+  "ask the user" and nothing else. An uninstall clears both.`
+			},
+			STIM_NO_DEVICE: {
+				summary: "no usable phone, or the owned simulator or emulator could not be created or booted",
+				separator: "--- DEVICE AND CAPACITY CODES ---",
+				body: () => `STIM_NO_DEVICE
+  With \`--device\`, no physical device answered the selection: none connected,
+  a named serial/UDID that is not connected, several connected with none named
+  (the refusal lists them), or one that is connected but unusable -- an
+  unauthorized Android device, or an iPhone that is unpaired or has Developer
+  Mode off. Hardware is never created or booted, so there is nothing to retry
+  into existence: fix the cable, the trust prompt, or Developer Mode.
+  Otherwise the owned simulator/emulator could not be created or could not
+  reach a booted state. \`stim doctor\` checks the toolchain; \`stim status\` says what
+  Stim thinks it owns. Re-running the command creates a fresh owned device
+  when the recorded one is gone.
+  On iOS a slow first boot is waited out for up to ten minutes while the
+  simulator still reports Booting -- a long silent wait on a loaded machine
+  is patience, not a hang. The failure names the udid and the wait.
+  On Android the emulator's own stdio is captured to
+  the global workspace logs/emulator.log (truncated per boot), and when it printed a
+  \`FATAL |\` / \`ERROR |\` / \`PANIC:\` line THAT is the message and the remedy
+  you get -- the disk-space refusal ("Not enough space to create userdata
+  partition") is the case this exists for. The generic toolchain remedy above
+  is only what you see when neither the log nor the failure itself identifies
+  the cause. An ENOSPC failure points at disk space instead: owned Android AVDs
+  normally live under ~/.android/avd, and a booted AVD can use several GB. A
+  boot whose emulator process exited is also reported at once rather than after
+  the full cold-boot timeout.
+
+"this project's sim is X, but --device-type asked for Y"
+  The project already owns a simulator of a different model, and Stim will
+  not silently boot a different one. Reap it (\`worktree remove\`, or
+  \`gc --delete\`) and run \`stim ios\` again to create the requested model.
+  That loses the old sim's app state.`
+			},
+			STIM_DEVICE_BUSY: {
+				summary: "another workspace holds the lease on that phone and the wait ran out",
+				body: () => `STIM_DEVICE_BUSY
+  Only on a \`--device\` run. Another workspace holds the lease on that phone,
+  and the wait ran out: the message names the holder root, the device, and the
+  expiry as a clock time and a remaining duration, and \`--json\` adds
+  \`lease: { platform, id, deviceName, holder, expiresAt }\`. In order, the
+  remedies are: wait longer with \`--wait <seconds>\`, pick another device by
+  id, or \`--no-wait\`, which installs with NO lease -- and when both
+  workspaces build the same app id, that install terminates the app the holder
+  is running. Two other cases refuse with this code and no wait at all: a lease
+  file that does not parse (\`lease\` fields null, the file named -- nothing may
+  take that device until it is dealt with), and this workspace's OWN lease with
+  no token left in its \`state.json\` (its workspace directory was recreated).
+  The remedy for that last one is \`stim device unlock\`, which releases by
+  holder rather than by token.`
+			},
+			STIM_DEVICE_LOST: {
+				summary: "the lease was gone or re-held at the pre-install check; rerun",
+				body: () => `STIM_DEVICE_LOST
+  Only on a \`--device\` run. The run held a lease, and the raise before the
+  install found it gone or held under another token -- another workspace took
+  the device in that window. The message names the new holder and its expiry.
+  Run the command again; it waits for that lease under \`--wait <seconds>\`.
+  AFTER the install has started this is not a failure: the app is already on
+  the phone, so the run prints one warning, continues, and reports
+  \`lease: null\` in \`--json\`.`
+			},
+			STIM_AT_CAPACITY: {
+				summary: "concurrency.maxDevices reached; a refusal, not a queue",
+				body: () => `STIM_AT_CAPACITY
+  Only when concurrency.maxDevices is set (it is UNSET by default, so this never
+  fires unless you opted in). Booting a NEW owned device would exceed the cap:
+  the machine already has that many Stim-owned devices booted. It is a refusal, not
+  a queue -- \`ios\`/\`android\` are interactive-shaped, so Stim does not make
+  you wait at a prompt. The remedy is fixed: stop an environment
+  (\`stim stop\`) to free a device, or raise concurrency.maxDevices. A
+  workspace whose OWN device is already booted is never refused -- re-running
+  \`ios\` on an environment you already have is idempotent. (The build cap
+  behaves differently: a compile WAITS for a free slot rather than refusing.
+  See \`guide lifecycle concurrency\`.)`
+			},
+			STIM_BUILD_SLOT_TIMEOUT: {
+				summary: "the maxBuilds wait gave up with every slot held by a running process",
+				body: () => `STIM_BUILD_SLOT_TIMEOUT
+  Only when concurrency.maxBuilds is set. The build cap does not refuse, it
+  WAITS -- this code is that wait giving up: ~90 minutes elapsed and every one
+  of the N slots was still held by a running process, or by a holder Stim could
+  not identify. A dead
+  builder's slot is reclaimed within a poll, and a recycled pid does not hold a
+  slot, so this is never a slot leaked by a crash; it is either that many
+  genuinely long compiles, or a slot directory whose owner is not really
+  building. A slot whose holder cannot be identified at all is skipped while any
+  other slot is merely busy, and becomes STIM_CLAIM_REFUSED only when no slot is
+  left to wait for. Slots live under ~/.stim/build-slots and
+  the message names the directory: remove the slot of a builder that is not
+  building, or raise concurrency.maxBuilds
+  (\`guide lifecycle concurrency\`).`
+			},
+			STIM_NO_REMOTE_SESSION: {
+				summary: "the backend could not use agent-device, or metro.tunnel names an unusable provider",
+				separator: "--- REMOTE-DEVICE CODES (`ios --remote <proxy|eas>` / `android --remote <proxy|eas>`) ---",
+				body: () => `STIM_NO_REMOTE_SESSION
+  The selected backend could not use agent-device, or metro.tunnel names a
+  provider or mode this workspace cannot use (e.g. "expo" on a bare RN
+  project). The remedy line says which. Nothing was created yet.`
+			},
+			STIM_REMOTE_PROXY_CONFIG: {
+				summary: "--remote proxy needs AGENT_DEVICE_DAEMON_BASE_URL and AGENT_DEVICE_DAEMON_AUTH_TOKEN",
+				body: () => `STIM_REMOTE_PROXY_CONFIG
+  \`--remote proxy\` requires AGENT_DEVICE_DAEMON_BASE_URL and
+  AGENT_DEVICE_DAEMON_AUTH_TOKEN. These variables provide credentials after
+  proxy is selected. They never select the backend.`
+			},
+			STIM_REMOTE_EAS_UNAVAILABLE: {
+				summary: "--remote eas needs eas-cli",
+				body: () => `STIM_REMOTE_EAS_UNAVAILABLE
+  \`--remote eas\` requires eas-cli. Proxy environment variables do not change
+  this selection and are not passed to EAS.`
+			},
+			STIM_REMOTE_PLATFORM_MISMATCH: {
+				summary: "the recorded remote session belongs to the other platform; stop, then rerun",
+				body: () => `STIM_REMOTE_PLATFORM_MISMATCH
+  This workspace already has a recorded remote session, and it belongs to the
+  OTHER platform ("Session <id> belongs to android, not ios"). A workspace
+  holds one remote session, and Stim will not end the recorded one to make
+  room -- it may be mid-run for whoever started it. Run \`stim stop\` for this
+  workspace, then re-run with the platform you want. Nothing was created here.`
+			},
+			STIM_REMOTE_SESSION_STATE: {
+				summary: "the EAS session was created but its state could not be recorded, so Stim stopped it",
+				body: () => `STIM_REMOTE_SESSION_STATE
+  The EAS session was created and is healthy, but recording it in this
+  workspace's state failed (an unwritable STIM_HOME, a full disk). A session
+  nothing references is a session nothing will ever stop, so Stim stopped the
+  one it had just created and removed its ownership claim before reporting:
+  this code means nothing is running and nothing is still billing. Repair the
+  state storage the message names, then run the remote command again.`
+			},
+			STIM_REMOTE_SESSION_CLEANUP: {
+				summary: "Stim could not prove an EAS session ended; eas simulator:stop --id",
+				body: () => `STIM_REMOTE_SESSION_CLEANUP
+  Stim tried to end an EAS session and could not PROVE it ended: \`eas
+  simulator:stop\` failed, or its output did not confirm the stop, or the
+  session stopped but its claim in the machine ledger could not be removed.
+  This is a refusal rather than a note because a session that did not stop
+  BILLS until its duration cap. The remedy names the exact command --
+  \`eas simulator:stop --id <id>\` -- and for a ledger that outlived its
+  session, the ledger path to repair. The same code covers a recorded session
+  that could not be verified before replacement: inspect it, then \`stim stop\`.`
+			},
+			STIM_REMOTE_METRO_WRONG: {
+				summary: "the tunnel reaches a Metro that is not this workspace's",
+				body: () => `STIM_REMOTE_METRO_WRONG
+  The gate that proves a tunnel still reaches THIS workspace's Metro failed --
+  before a session or a build, whether the tunnel is Expo's own, one Stim
+  started (metro.tunnel: cloudflared/ngrok/auto), or a named metro.publicUrl.
+  The usual cause: the tunnel was built for a port this workspace no longer
+  holds (a stale one survived a \`stop\`/\`start\` that reserved a different
+  port), and it now serves ANOTHER workspace's dev server -- healthy, and
+  wrong. Re-run \`stim start\` (it prints the port it reserved) and, for a
+  manual tunnel, rebuild it against that port.`
+			},
+			STIM_REMOTE_METRO_UNREACHABLE: {
+				summary: "a remote start could not create its managed tunnel or tell the device where Metro is",
+				body: () => `STIM_REMOTE_METRO_UNREACHABLE
+  A remote start could not create its selected managed tunnel, or the device
+  could not be told where Metro is. Follows the same remedy as
+  STIM_NO_REMOTE_SESSION's tunnel guidance -- set metro.tunnel, or use
+  metro.publicUrl for an existing endpoint.`
+			},
+			STIM_RELOAD_AMBIGUOUS: {
+				summary: "both owned apps are live; name the platform",
+				separator: "--- RELOAD CODES (`stim reload [ios|android]`) ---",
+				body: () => `STIM_RELOAD_AMBIGUOUS
+  Both owned apps are live. Name ios or android; Stim never guesses.`
+			},
+			STIM_RELOAD_RELEASE: {
+				summary: "the live app has embedded JS; run a Debug build first",
+				body: () => `STIM_RELOAD_RELEASE
+  The live app was launched with embedded JavaScript. Run the platform command
+  with a Debug configuration or variant first.`
+			},
+			STIM_RELOAD_STOPPED: {
+				summary: "the recorded app is gone, its device is not live and owned, or the process could not be proven",
+				aliases: ["STIM_RELOAD_UNOWNED", "STIM_RELOAD_PROBE_FAILED"],
+				body: () => `STIM_RELOAD_STOPPED / STIM_RELOAD_UNOWNED / STIM_RELOAD_PROBE_FAILED
+  The recorded app is gone, its exact device is not live and owned by this
+  workspace, or simctl/adb could not prove the process exists. No launch or
+  device lifecycle action is taken; follow the printed platform-command or
+  process-probe remedy.`
+			},
+			STIM_RELOAD_FAILED: {
+				summary: "the reload failed; the remedy differs by shape -- read it before acting",
+				body: () => `STIM_RELOAD_FAILED
+  The Metro websocket reload did not reach a peer Stim could identify. Two
+  shapes reach this code and the remedy differs. Read it rather than assuming.
+
+  METRO DID NOT ANSWER. The probe timed out after 2 seconds, or the socket
+  errored. Nothing is known about the app, so the remedy is to run the same
+  reload again, and to check the dev server with stim doctor if it keeps
+  timing out. Do not touch the device for this one.
+
+  METRO REPORTS NO PEER FOR THE APP. Stim broadcasts a reload anyway before
+  giving up, because matching is best-effort and an unmatched peer may still be
+  this app, so VERIFY THE UI FIRST -- the app may already have recovered. If it
+  did not, retry: a client reconnects to Metro every 2 seconds, which is also
+  this probe's timeout, so a single miss can be a reconnect window rather than
+  an app that never connected. If it stays unreachable on iOS, an error in the
+  first bundle leaves the app without a packager connection at all and no retry
+  will make it a peer. The remedy then routes the agent to the device's own
+  controls in its existing automation session: press the error screen's Reload
+  button, or open the dev menu and press Reload when no error screen is
+  showing. The printed agent-device open command is the last resort; it
+  relaunches that app on that device with this workspace's Metro port and loses
+  in-memory state. Keep the existing --session flag and verify afterward.
+
+  MORE THAN ONE MATCHING PEER IS NOT A FAILURE. A workspace Metro serves one
+  app, so several matching peers are that app on several devices. Stim reloads
+  every one of them and reports the count in the facts as targets.`
+			},
+			STIM_WORKTREE_REMOVAL_IN_PROGRESS: {
+				summary: "a managed remote start found worktree remove holding the lock; wait, then rerun",
+				separator: "--- DEV-SERVER CODES (`stim start`) ---",
+				body: () => `STIM_WORKTREE_REMOVAL_IN_PROGRESS
+  A managed remote start found that \`stim worktree remove\` owns the
+  worktree lock. The start did not register the project or create a tunnel.
+  Wait for removal to finish, then run \`stim start --remote\` again.`
+			},
+			STIM_REMOTE_START_REQUIRED: {
+				summary: "a running server cannot gain a remote tunnel; stop, then start --remote, or metro.publicUrl",
+				body: () => `STIM_REMOTE_START_REQUIRED
+  A healthy bare or Expo server was started without its required remote
+  tunnel. A running server cannot gain that option. For a Stim supervisor,
+  run \`stim stop\`, then \`stim start --remote\`. For an external server,
+  configure metro.publicUrl or let Stim supervise the server.`
+			},
+			STIM_BARE_DEPS: {
+				summary: "the supervisor cannot host Metro from the project's node_modules; the @stim-cli/metro capture note",
+				aliases: ["STIM_BARE_LOAD", "STIM_BARE_API"],
+				body: () => `STIM_BARE_DEPS / STIM_BARE_LOAD / STIM_BARE_API  (bare RN)
+  The supervisor hosts Metro out of the PROJECT's node_modules, so metro,
+  @react-native/dev-middleware and @react-native-community/cli-server-api must
+  be installed there and must match the project's React Native. DEPS = not
+  resolvable (install them), LOAD = installed but threw while loading,
+  API = loaded but is not the API Stim expects (mismatched versions).
+
+"@stim-cli/metro is not installed ... so bundler and client logs will not be
+captured"  (in metro.ndjson, bare RN)
+  The dev server is serving; only capture is missing, so \`logs\` would report
+  a quiet timeline for a broken build. Install \`@stim-cli/metro\` as a
+  devDependency of the project.`
+			},
+			STIM_EXPO_BIN: {
+				summary: "node_modules/.bin/expo is missing; install dependencies",
+				body: () => `STIM_EXPO_BIN  (Expo)
+  node_modules/.bin/expo does not exist. Install the project's dependencies.`
+			},
+			STIM_METRO_TIMEOUT: {
+				summary: "the supervisor is alive but Metro or the tunnel was not ready within the wait; --wait 180",
+				body: () => `STIM_METRO_TIMEOUT
+  "The dev server did not answer on port <n> within <s>s."
+  The supervisor is alive, but Metro or its requested Expo tunnel is not ready.
+  \`start\` has already
+  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_SUPERVISOR_EXITED: {
+				summary: "the dev server failed outright; the quoted supervisor.log tail is the real error",
+				body: () => `STIM_SUPERVISOR_EXITED
+  "The supervisor exited (<code|signal>) before the dev server came up"
+  The dev server failed outright, and the quoted evidence is the real error:
+  the supervisor.log tail if it wrote one, plus this attempt's error records
+  from the timeline (an expo child's config error -- a PluginError, a bad app
+  config -- lands THERE, not in supervisor.log). \`stim logs --errors\` has
+  the full records. Fix that and run \`start\` again.
+
+  "Cannot reuse or replace the recorded supervisor: ..."
+  A live record has no verifiable OS process identity, or the workspace and
+  registry records disagree. Nothing new was started; the old process is
+  left running. If inspection is denied, retry with permission to inspect
+  Stim's processes. For a legacy record, stop the server with the tool that
+  started it before retrying. Never reconstruct ownership from a process
+  name, port, or wall-clock timestamp.`
+			},
+			STIM_BAD_ARG: {
+				summary: "an argument, setting, directory, flavor, or device name refused before anything starts",
+				aliases: ["STIM_NO_PROJECT"],
+				body: () => `STIM_BAD_ARG / STIM_NO_PROJECT
+  The command refused before doing anything: an unusable --wait value, a known
+  setting with the wrong type ("Invalid <key> setting <value>. Expected <shape>."
+  -- \`guide settings\` names the type each key takes), an invalid
+  Metro tunnel setting, an invalid android.dataPartitionSizeGb value, an unsafe
+  android.avdConfig key or fragment, a malformed ios.signingIdentity,
+  ios.signingIdentitySha1 or ios.lanHost value, \`--device\` with an empty
+  serial or UDID, \`--device\` together with \`--remote\`, 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), an
+  android/app/build.gradle that declares product flavors with
+  no variant selected (the refusal names the debug variants), or a
+  \`--device-type\`, \`--runtime\` or \`--system-image\` name that is BLANK or
+  is not installed on this machine. For the unknown-name case the installed
+  names are printed in the message -- the versions \`xcrun simctl list
+  runtimes\` reports, the models those runtimes can actually CREATE (not the
+  whole \`simctl list devicetypes\` table, which also names watchOS, tvOS and
+  visionOS models no iOS runtime offers), or the system images the SDK has --
+  so the remedy is to re-run with one of them. An ios.deviceType, ios.runtime
+  or android.systemImage setting is checked the same way, and the check applies
+  even when this workspace ALREADY owns a device, so a name that could never
+  create anything is caught rather than left to a later run.
+  These errors are caught before the port is reserved and before any build or
+  device work, so nothing was started. The one listing they need
+  (\`simctl list runtimes\`, the SDK's system-images directory) runs only when
+  a name was actually given, and a listing that fails is reported as
+  STIM_NO_DEVICE naming the tool, never as a crash.`
+			},
+			STIM_LOCK_REFUSED: {
+				summary: "a directory lock is held by a removal, which is never waited out",
+				separator: "--- COORDINATION CODES (any command that shares a resource) ---",
+				body: () => `STIM_LOCK_REFUSED
+  A directory lock that serialises two commands over the same thing -- this
+  workspace's managed tunnel, its managed remote worktree, the machine's EAS
+  project ledger -- is held by a REMOVAL, and a removal is never waited out:
+  what it protects will not exist when the lock frees. Nothing was created.
+  The message names the lock and the purpose holding it (\`worktree removal\`,
+  \`workspace removal\` -- both are \`stim worktree remove\`). Let it finish,
+  then run the command again. \`start --remote\` reports this same case as
+  STIM_WORKTREE_REMOVAL_IN_PROGRESS instead.`
+			},
+			STIM_LOCK_TIMEOUT: {
+				summary: "a lock held past the wait; workspace-process and short directory locks",
+				body: () => `STIM_LOCK_TIMEOUT
+  The same locks, held by an ordinary command that is still running, for
+  longer than the wait -- 60s by default, 4 minutes for the remote-session and
+  EAS project locks, and ~90 minutes for the \`worktree warm\` lock, which one
+  \`--refresh\` can hold for a whole dependency install. That wait prints its
+  elapsed waiting time and holder every 30 seconds (\`lock        waiting 40s
+  for stim worktree warm --refresh (pid 41233)\`) and the refusal names the same holder
+  and the lock directory under ~/.stim/warm-locks.
+  A lock whose owner died is taken over automatically (its recorded
+  process identity is checked every poll), so this means another Stim command really
+  is working on this workspace: wait for it and retry. If nothing is running,
+  the message names the lock directory and removing it is safe. The same error
+  code also covers the short directory-lock timeout below.
+
+"Timed out waiting for the lock at <path>."
+  Short directory locks serialize writes to config, workspace state, device
+  leases, ownership records, metadata, and cache manifests. The path identifies
+  the lock. A lock older than 10s is taken over automatically. Wait for the
+  command holding it; if none is running, remove the named directory.`
+			},
+			teardown: {
+				summary: "an unmanaged port, an unverified supervisor, and a failed device teardown",
+				separator: "--- TEARDOWN AND WORKSPACE REFUSALS ---",
+				body: () => `"metro       refusing to kill port <n>: ... runs from <dir>, outside
+<project>"  (stop)
+  Stim only signals processes it launched and whose saved identity still
+  matches. Stop an externally started server with the tool that started it.
+  Matching this workspace's port or directory does not authorize cleanup,
+  and stop has no override for process ownership.
+
+"stop        refusing to signal supervisor pid <n>: ..."  (stop)
+  The records disagree, the saved OS identity is unavailable, or it records a
+  port this project did not reserve. If process inspection is denied, retry
+  with permission to inspect the processes Stim started. A pid is a number the OS reuses, so it is not
+  signalled. The port reservation is KEPT -- it is the only handle a retry
+  has. Check \`ps -p <n>\` and \`stim status\` before signalling by hand.
+
+"supervisor pid <n> did not exit within 10s of SIGTERM"  (stop)
+  Deliberately not escalated to SIGKILL: the supervisor may be mid-write on the
+  very log files \`logs\` reads. The device is left alone and the port stays
+  reserved. Re-run \`stop\`, or signal it yourself: kill -9 -<n> (note the
+  minus -- it is a process group).
+
+"teardown failed: <reason>"
+  Stim could not release the owned device and keeps its record for a retry.
+  \`worktree remove\` exits 1 without removing the worktree while the device is
+  still tracked. Fix the reported cause and re-run.`
+			},
+			remove: {
+				summary: "worktree remove refused a dirty tree: what it restores itself and what --force discards",
+				body: () => `"Refusing to remove <path>: uncommitted changes / untracked files / commits
+not on any remote"  (worktree remove)
+  A native build rewrites tracked files, and Stim now RESTORES the one class
+  it can prove is not work: when the only dirt left is \`pod install\` churn
+  (\`<app>/ios/Podfile.lock\`, \`<app>/ios/*.xcodeproj/project.pbxproj\`,
+  tracked and unstaged), \`worktree remove\` runs the checkout itself and says
+  so per file -- those files die with the worktree either way, and a lockfile
+  change anyone meant would have been committed. ONE other dirty path and the
+  whole set is refused, churn included, so this never eats real work.
+  When it does refuse, the refusal PRINTS THE DIRTY PATHS, and the restore
+  command under it carries those same paths: run it as printed rather than
+  reaching for --force.
+  It is built from what git reported, so in a monorepo it names
+  \`apps/<app>/ios/Podfile.lock\` rather than an \`ios/...\` example that would
+  fail with "did not match any file(s) known to git".
+  A setup script that rewrites tracked assets (brand icons, generated config)
+  produces the same refusal, with the same treatment: restore the paths the
+  refusal actually named.
+  Use --force only when you genuinely intend to discard work; it deletes
+  uncommitted and untracked files permanently.`
+			},
+			STIM_MAIN_DIRTY: {
+				summary: "warm --refresh will not move a source checkout with local work or an operation in progress",
+				body: () => `STIM_MAIN_DIRTY
+  \`worktree warm --refresh\` writes to the SOURCE CHECKOUT, and it refuses one
+  it cannot move: tracked files with uncommitted changes (the refusal names
+  them), or a rebase or merge in progress. Untracked files are not a reason to
+  refuse -- but git itself refuses a fast-forward that would overwrite one, and
+  that reports this code too, quoting git. The remedy is the exact line that
+  clears it: commit, \`git -C <source-checkout> stash push -u -m warm-refresh\`,
+  or \`git -C <source-checkout> rebase --abort\`. Nothing was installed or
+  copied. Plain \`stim worktree warm\` does not care: it copies from a dirty
+  source checkout exactly as it always has.`
+			},
+			STIM_MAIN_DETACHED: {
+				summary: "warm --refresh needs a branch to fast-forward, not a detached HEAD",
+				body: () => `STIM_MAIN_DETACHED
+  The source checkout's HEAD is detached, so there is no branch to fast-forward
+  and no upstream to fast-forward it to. Run
+  \`git -C <source-checkout> checkout <branch>\` and warm again. \`--refresh\`
+  never picks a branch for you; a checkout whose job is to seed worktrees
+  should sit on a branch someone chose.`
+			},
+			STIM_MAIN_DIVERGED: {
+				summary: "the source checkout is both ahead of and behind its upstream; warm --refresh will not merge",
+				body: () => `STIM_MAIN_DIVERGED
+  The source checkout's branch has commits its upstream does not, AND its
+  upstream has commits it does not. A fast-forward is impossible, and
+  \`--refresh\` will not merge or reset someone else's checkout to make one:
+  that decision is yours. Rebase or merge it yourself, then warm again. The
+  message reports both counts. Nothing was installed or copied.`
+			},
+			STIM_DEPS_INCOMPLETE: {
+				summary: "the last install recorded for the lockfile on disk now did not finish, so warm will not copy it",
+				body: () => `STIM_DEPS_INCOMPLETE
+  \`worktree warm\` refuses to copy dependencies the source checkout never
+  finished installing. \`--refresh\` records a COMPLETED install of the lockfile
+  it read under ~/.stim/warm-installs; an install that failed, or whose process
+  was killed, leaves that record saying unfinished. A plain warm reads it after
+  it takes its claim and before it copies, and this code is what it prints when
+  the unfinished install is of the lockfile AS IT STANDS NOW. Without it the
+  copy carries a partial node_modules and exits 0, and nothing else in the run
+  says so: the refresh reported its own STIM_DEPS_FAILED in its own terminal,
+  and a refresh that was killed reported nothing anywhere. Nothing was copied.
+  Run \`stim worktree warm --refresh\`: it reinstalls rather than skipping for
+  exactly the same record, and a plain warm copies once that install completes.
+  Two states deliberately do NOT produce this code. A record of a DIFFERENT
+  lockfile says nothing about the one on disk now, whose dependencies may well
+  have been installed since; and a repository with no record at all -- every
+  repository before its first \`--refresh\` -- copies as it always has.
+  In a monorepo the record is keyed on the directory that owns the lockfile,
+  which is usually the repository root, so every app of it reads the same one.`
+			},
+			warm: {
+				summary: "two warm refusals whose text is incomplete, known and not fixed",
+				body: () => `"Could not warm this worktree: EACCES: permission denied, mkdir
+'<home>/warm-locks/<name>.lock'"  (worktree warm --refresh)
+  A STIM_HOME that \`--refresh\` cannot write. The refusal itself is right -- it
+  writes to the source checkout, so it will not run without a claim -- but it
+  carries no \`failed: <CODE>\` line, because EACCES is not a Stim code, and no
+  fix line. Make STIM_HOME writable, or set STIM_HOME to somewhere writable,
+  then run it again. A plain warm degrades in this state rather than refusing.
+
+"... the claim path is a file, not a claim directory", with a \`rm -rf\` that
+changes nothing  (worktree warm --refresh)
+  When \`$STIM_HOME/warm-locks\` or STIM_HOME itself is a regular FILE, the
+  refusal names \`warm-locks/<name>.lock\` -- a path that cannot exist under a
+  file -- so running the printed removal does nothing and the next run refuses
+  identically. Remove the file that is in the way and run it again. A plain
+  warm copies unsynchronised in this state.
+
+  Both are documented rather than fixed: appandflow/stim#696.`
+			},
+			carry: {
+				summary: "worktree warm copy results, lockfile mismatches, and remedies",
+				body: () => `"carry       incomplete: ... ignored entries copied, ... kept, ... failed"
+(worktree warm)
+  At least one entry could not be copied. The command exits 1 and names each
+  failure. Existing entries stay untouched; any files already published remain.
+  Inspect failed paths before retrying, because existing directories are skipped
+  whole. "complete" means the eligible copy finished, not that dependencies
+  are installed or match this branch. Progress and results go to stderr,
+  with empty stdout.
+
+"carry       carried <dir>/Pods does not match the <dir>/Podfile.lock on disk here"
+  Warm copied ignored Pods from the source checkout, but their Manifest.lock
+  differs from the tracked Podfile.lock in this worktree. Warm does not change
+  tracked files. Run the printed pod-install command before building directly.
+  \`stim ios\` detects a mismatch and runs \`pod install\` for you.
+
+"carry       carried <dir>/Pods but there is no <dir>/Podfile.lock"
+  Warm copied Pods but the destination has no Podfile.lock. Follow the printed
+  pod-install command before building.
+
+"carry       carried dependencies may be stale: they do not match ..."
+  The source checkout's lockfile differs from this branch's lockfile. Run the
+  printed package-manager command before building. A carry whose lockfile
+  matches is silent; the warning means a real difference.
+
+  If the source checkout has no dependencies to copy, use this project's
+  package manager to install them. Warm does not install dependencies or prove
+  the app is ready, unless \`--refresh\` installed them in the SOURCE CHECKOUT
+  first; even then the copy can still carry a lockfile this branch does not
+  have, which is exactly what these carry warnings report.`
+			},
+			environment: {
+				summary: "npx registry E401/E404, the Node floor, no free Metro port, the reservation race",
+				separator: "--- ENVIRONMENT ---",
+				body: () => `"npm error code E401 / E404" while \`npx\` resolves the stim package
+  The repo probably pins a private registry in \`.npmrc\`, so \`npx\` looked for
+  the package there instead of on npm. Use the public registry for this command:
+
+    npx --registry=https://registry.npmjs.org stim <command>
+
+  A line such as \`npm warn exec ... will be installed\` is normal when using
+  the no-install form.
+
+"Unsupported engine" or a syntax error before Stim starts
+  Stim requires Node 20.19.4 or later on Node 20, or Node 22.12.0 or later.
+  Switch Node versions, then run the command again.
+
+
+"Found no free Metro port between ..."
+  200 consecutive ports are claimed or occupied. \`stim status\` shows what
+  Stim knows about; the rest is other software.
+
+"Could not reserve a Metro port after 5 attempts"
+  Several commands raced for the same ports and each one lost. Nothing is
+  wrong; retry.`
+			},
+			sandbox: {
+				summary: "running under a sandboxing harness: EPERM under STIM_HOME, CoreSimulatorService, adb",
+				body: () => `RUNNING UNDER A SANDBOX
+
+  An agent harness that sandboxes shell commands typically permits writes
+  inside the project and blocks the rest. Three things Stim needs sit outside
+  that boundary, and none of the failures names the sandbox:
+
+    EPERM: operation not permitted, mkdir '<STIM_HOME>/workspaces/...'
+      writes to STIM_HOME (~/.stim unless set)
+
+    CoreSimulatorService connection became invalid   (macOS)
+    Unable to locate device set: ... Code=61 "Connection refused"
+      the simulator service simctl talks to over XPC
+
+    ADB server didn't ACK
+    could not install *smartsocket* listener: Operation not permitted
+      the adb server socket on tcp:5037
+
+  Measured on Claude Code and on Codex: the three fail the same way in both,
+  so this is the shape of the problem, not one harness's quirk. Codex also
+  blocks network egress by default, which breaks a cache lookup and a fetch.
+
+  \`stim doctor\` names this when a write to STIM_HOME actually fails, not
+  merely when a harness that can sandbox is present, and
+  \`stim doctor --fix\` writes the three keys into .claude/settings.local.json,
+  the per-user file, merging with what is there. It refuses under Codex, which
+  has no per-path allowance to add, and refuses any settings file it cannot
+  parse rather than replace it: comments make one unparseable here even though
+  Claude Code accepts them. Claude Code reads project settings from the
+  directory a session starts in, so in a monorepo the file has to sit at that
+  root to count, and a file written inside a worktree goes when the worktree
+  does.
+
+  Two ways out, and choosing at the start of a session beats discovering it
+  three failures in. Either run Stim with the harness's sandbox disabled, or
+  allow the three. In Claude Code that is settings.json:
+
+    sandbox.filesystem.allowWrite     ["~/.stim"]
+    sandbox.network.allowMachLookup   ["com.apple.coresimulator.*"]
+    sandbox.network.allowLocalBinding true
+
+  In Codex the sandbox is one flag, \`codex -s\`, with no per-path allowance:
+  workspace-write still refuses STIM_HOME.
+
+  A git credential helper is often blocked too. It prints \`failed to store\`
+  on a fetch that otherwise succeeded, and is safe to ignore.`
+			},
+			STIM_CONFIG_CORRUPT: {
+				summary: "~/.stim/config.json is not valid JSON and Stim never resets it",
+				body: () => `STIM_CONFIG_CORRUPT  ("Stim config at <path> is not valid JSON")
+  Any command can raise it: every command reads ~/.stim/config.json first.
+  The file holding every owned-device record will not parse, and Stim never
+  resets it for you -- a silent reset would orphan every simulator it names.
+  Repair the file, or move it aside (\`mv <path> <path>.broken\`) and accept
+  that the devices it recorded become orphans you delete by hand.`
+			}
+		}
+	},
+	lifecycle: {
+		summary: "The full worktree -> start -> ios/android -> logs -> teardown flow, with sections for builds, devices and flags",
+		preamble: () => `ENVIRONMENT LIFECYCLE
+
+Two workflows share steps 2 through 6.
+
+SINGLE CHECKOUT: work in place, on a branch, in one directory. There is no
+step 1, and step 7 reclaims the environment without deleting the tree, which
+stays because it is the source checkout. That directory is your workspace, and
+no rule here about keeping the source checkout fit as a seed applies to it.
+
+WORKTREE: the checkout you cloned is a seed. It stays clean and on the default
+branch so every worktree warmed from it starts current. Here the source checkout
+is infrastructure, not a workspace, and every rule below about its fitness as
+a seed belongs to this workflow.
+
+  # 1. Create a linked worktree with Git, unless a harness already did.
+  #    Choose the branch, path, and base ref with Git.
+  git worktree add -b app/412 ../app-412 HEAD
+  cd ../app-412
+  stim worktree warm
+
+  # Warm copies missing ignored state from the source checkout; it does not
+  # install dependencies.
+  # In a monorepo, enter the app directory before starting the dev server.
+
+  # Optional: bring the SOURCE CHECKOUT up to date first, then copy that.
+  stim worktree warm --refresh
+    lock        acquired
+    checkout    main 3 commits behind origin/main -> fast-forwarded to 9f2c1a3
+    deps        source /w/main: pnpm-lock.yaml changed -> pnpm install (41s)
+    pods        source /w/main/apps/mobile: ios/Podfile.lock unchanged -> skipped
+
+  # 2. The dev server, under a detached supervisor. Blocks until it is
+  #    verifiably THIS project's, then hands your shell back.
+  stim start
+    port       8082 (reserved)
+    supervisor pid 41233
+
+  # If stale Metro transforms or file-map state require recovery:
+  stim start --reset-cache
+  # Restarts only this app's verified owned Metro, retaining its port/devices.
+  # Uses a fresh persistent cache namespace, not deletion of shared cache files.
+  # Other apps and worktrees keep their caches. Subsequent starts reuse the new
+  # namespace; another reset changes it again. Native build caches are unchanged.
+  # Expo requires SDK 54+ and Stim's config adapter. Custom file-map cache
+  # managers must honor Metro's fileMapCacheDirectory for file-map invalidation.
+
+  # 3. Owned device booted, native inputs fingerprinted, cached build
+  #    installed (or built), app launched wired to port 8082, device-log
+  #    collector attached.
+  stim ios          # or: stim android
+    device      stim-app-412 (iPhone 17 26.5) (BF2A..) booted (9s)
+    fingerprint a3f9b1.. hit (2s)
+    install     from cache (3s)
+    launch      com.example.app (1s)
+
+  # 4. Reproduce the affected behavior and inspect the baseline errors.
+  #    For a clean check, require exit 0 AND no matching errors.
+  #    Human mode prints "No matching log records" on stderr for zero matches.
+  #    Exit 0 alone means the query succeeded, even when it printed errors.
+  stim logs --errors
+
+  # 5. Edit the JS. Fast Refresh applies it; no Stim command is involved.
+  #    For UI work, wait for the expected UI and repeat the affected interaction
+  #    on the reported device, using the existing automation session if any.
+  stim logs --errors
+  #    Retain proof: a screenshot, recording, or relevant runtime output.
+  #    See: stim guide lifecycle verification
+
+  # 6. Pausing: supervisor halted, collectors reaped, owned device SHUT DOWN
+  #    (never deleted), port freed. Coming back costs a boot, not a create.
+  stim stop
+
+  # 7. Remove this linked worktree and its environment. This also works for
+  #    unwarmed worktrees with no Stim registry entry. Git-created branches stay.
+  stim worktree remove
+
+Steps 2 and 3 are ordered, not interchangeable: \`ios\` and \`android\` never
+start the bundler, and refuse with STIM_NO_METRO when nothing holds the
+reserved port. That refusal costs a second; the alternative costs four minutes
+and produces an app that cannot load a bundle.
+
+Repeat step 3 whenever a NATIVE input changes. A JS-only edit needs nothing --
+that is what Fast Refresh over the running dev server is for. \`stim reload\` is
+not part of the normal workflow. It is the explicit recovery path when Fast
+Refresh cannot clear the current screen, and on Android after a failed first
+bundle load. It reloads JavaScript and never restarts the app. Use \`stim
+reload ios\` or \`stim reload android\` to select a platform when both owned
+apps are live. For a physical device that reached Metro, use \`agent-device
+metro reload --metro-port <reported-port>\`. The detected iOS Local Network
+first-load remedy uses agent-device UI automation because no Metro peer exists
+yet. It never builds, installs, boots, or cold-launches. It acts only on a live
+app on this workspace's owned local simulator or emulator, and refuses release
+builds, stopped or unowned devices, a missing or foreign Metro, and an
+ambiguous no-platform request. Every reload goes over this workspace's Metro
+websocket, on both platforms. It never reopens a development-client URL,
+because that restarts the app rather than reloading its JavaScript.
+
+How the message is addressed depends on the dev server, and \`strategy\` in
+the facts reports which you got. Where Metro can name its clients, Stim
+addresses every peer matching the platform and reports \`metro-websocket\`. A
+workspace Metro serves one app, so those peers are this app on however many
+devices are attached to that port, and \`targets\` says how many peers the request
+addressed.
+The bare React Native dev server cannot name its clients at all, so Stim
+broadcasts: \`metro-broadcast\` means every app connected to that Metro
+was sent a reload request and Stim cannot confirm \`appId\` was among them. Verify the UI on
+\`deviceId\`; if it did not change, reload from the app's own error screen or
+dev menu.
+
+When Metro reports no peer for the app, Stim broadcasts a reload anyway before
+giving up, because matching is best-effort and an unmatched peer may still be
+this app. So verify the UI first: it may already have recovered. If it did not,
+retry: a client reconnects every 2 seconds, which is also this probe's timeout,
+so a single miss can be a reconnect window rather than an app that never
+connected. If it stays unreachable on iOS, an error in the first bundle leaves
+the app without a packager connection at all, and no retry will make it a peer.
+The command then routes the agent to the device's own controls in its existing
+automation session: press the error screen's Reload button, or open the dev
+menu and press Reload when no error screen is showing, and relaunch only when
+neither is reachable. Stim does not take over that stateful session.
+
+When Metro itself does not answer within the probe's 2 seconds, nothing is
+known about the app. The command says to retry and check the dev server rather
+than sending the agent to the device.
+
+A successful reload confirms that the request was sent. It does not wait for
+new JavaScript or observe the resulting UI. Verify the expected screen or
+interaction on the reported device and inspect \`stim logs --errors\` before
+claiming recovery; exit 0 alone does not prove it.
+
+An iOS simulator launch command has a 60-second deadline. This is separate
+from bundle delivery and readiness verification: it gives CoreSimulator time
+to accept the launch, not the app extra time to report readiness. A timeout
+still fails the launch; Stim does not automatically retry it.
+
+For an unverified Android launch, follow the emitted device-specific remedy.
+If the app is stuck before loading its first bundle, restart its process with
+the printed force-stop and launcher commands. Foregrounding the same process
+does not restart initialization. Confirm the bundle request and expected UI.
+
+DESTRUCTIVE COMMANDS -- ask the user first
+  gc --delete             deletes orphaned stim-* devices, tens of GB
+  gc --delete --cache all empties the shared build caches every project uses
+  gc --delete --cache <name>
+                          empties only the caches that carry <name>
+  worktree remove --force discards uncommitted and untracked work
+
+Permanent local deletion lives in exactly TWO commands: \`worktree remove\`
+(the workspace you name) and \`gc --delete\` (the machine). For a local device,
+\`stop\` shuts it down and never deletes it. For a recorded EAS session,
+\`stop\` irreversibly ends the session. Externally started servers are left
+alone, even when they use the reserved port. There is no \`--delete\` flag on
+\`stop\`.
+
+CAPACITY
+  A booted iOS sim is roughly 1-2 GB of RAM, an Android emulator 2-3 GB. On a
+  16 GB machine plan for 2-3 live environments. Nothing enforces this;
+  \`stim status\` is how you check -- it reports every workspace on the
+  machine, not just this one.
+
+TWO REPORTS, TWO QUESTIONS
+  "What is running" is \`stim status\`: live state, right now. "How much the
+  cache saved" is \`stim stats\`: aggregate counters for this project and for
+  the machine, with a hit rate and an estimate of the time saved (see
+  \`guide facts stats\`).`,
+		sections: {
+			readiness: {
+				summary: "implement optional pending/ready app logs, deadlines, errors, and platform isolation",
+				body: () => `OPTIONAL APP READINESS
+
+No package or SDK is needed. This applies to debug ios/android launches with
+Metro verification enabled, not release builds or --no-metro-check.
+
+1. Add this at app startup, before essential initialization:
+
+     if (__DEV__) console.info('[stim:readiness] pending');
+
+2. Use the app's real ready state: essential initialization succeeded, usable
+   content rendered, and the splash screen hidden. From that success path:
+
+     if (__DEV__) console.info('[stim:readiness] ready');
+
+   In an Expo root component with an existing isReady state:
+
+     useEffect(() => {
+       if (!isReady) return;
+       let active = true;
+       SplashScreen.hideAsync().then(() => {
+         if (active && __DEV__) console.info('[stim:readiness] ready');
+       }).catch(console.error);
+       return () => { active = false; };
+     }, [isReady]);
+
+   Import useEffect from react and SplashScreen as a namespace from
+   expo-splash-screen. Keep the pending log outside the component at module
+   scope, before startup work. Use the project's existing splash lifecycle;
+   do not add a splash dependency to a bare app just for this integration.
+   Static imports run before module-scope statements. If imported startup work
+   must opt into the wait, emit pending from an earlier app entry module before
+   loading that work. A failure before pending keeps the default check.
+   Cover login, onboarding, and deep links. Do not report ready merely on
+   root mount, on a timer, in a failure handler, or in finally.
+
+3. Run the platform command from the app directory. Check for the readiness
+   phase and inspect the UI on the reported device. Exercise a slow success,
+   a missing ready message, and a startup error. Retain the relevant output.
+
+Without an observed pending, Stim keeps its default 3-second stability window
+after bundle delivery. Managed Metro servers report the native bundle response
+finishing; build-complete output alone does not close an observed request.
+Without response capture, Stim falls back to the build-complete marker.
+When Android reports queued JavaScript loading, Stim waits for a device
+JavaScript log before starting stability, bounded by the bundle timeout.
+Pending must be observed before the stability window closes. It opts into
+waiting for ready until 30 seconds after the same completion signal.
+Repeated pending messages never extend the deadline. Ready can end the wait
+early; an app error or process exit interrupts it. No ready means readiness
+not confirmed, not a crash or successful readiness.
+
+Only exact standalone info/debug messages captured from this app's device log
+for this platform and current launch are accepted. Stale, other-platform,
+error-level, and embedded example messages are ignored. Unlabelled shared
+Metro output cannot identify a platform. If pending is not captured in time,
+including when device logs are unavailable, the default check applies.
+
+The app declares readiness; Stim does not inspect a rendered frame. This does
+not change launched JSON semantics or the need to inspect the expected UI and
+stim logs --errors. A reload request does not run this launch check.`
+			},
+			verification: {
+				summary: "reproduce the affected behavior, verify the change on the reported device, and retain proof",
+				body: () => `VERIFY THE CHANGE
+
+For a UI change or bug fix, decide what observable result would prove the task
+is complete. A successful build, a live process, or an empty log query does
+not prove that result.
+
+1. On the device reported by ios or android, reproduce the affected behavior
+   before editing and capture the baseline with stim logs --errors. If the
+   issue does not reproduce, record what you tried instead of claiming it did.
+2. Make the change. JavaScript and TypeScript normally use Fast Refresh;
+   native input changes need another ios or android run. Follow the printed
+   recovery remedy if an error screen remains or the native process exited.
+3. Use the full reported device ID with your UI automation tool. Continue in
+   the existing session for that device when one exists. Wait for the expected
+   content or control before inspecting the screen; launch evidence alone
+   does not prove that the first screen has rendered. Bound the wait and report
+   verification as incomplete if the expected state never appears.
+4. Repeat the affected interaction and check its expected outcome, then run
+   stim logs --errors. Read the records, not just the exit code. Earlier client
+   errors can remain after Fast Refresh; compare their timestamps with the
+   reproduction and check whether they recur. Do not relaunch just to clear
+   the log window. An empty query does not prove log capture succeeded.
+5. Retain a screenshot for a visible result or a short recording for an
+   interaction. Report what you exercised, what you observed, any unresolved
+   errors, and the proof location before stopping the app or removing the
+   worktree. If device access or another prerequisite prevents verification,
+   name the missing check.
+
+For a change without a UI effect, use the relevant runtime output or test
+result as proof instead of requiring an unrelated screenshot.`
+			},
+			progress: {
+				summary: "phase lines, the label set, heartbeats and their ~ estimate, what warm, start, stop and remove print",
+				body: () => `PROGRESS ON A LONG RUN
+  Native build progress goes to stderr. In \`--json\` mode, stdout carries only
+  the result payload. Plain \`start\` also prints progress on stdout. Every
+  progress line has the same shape -- two spaces, a label padded to eleven
+  columns, the FACT, and the time the step cost:
+
+    <label>     <fact> (<duration>)
+
+  The labels are a closed set, and nothing else is ever printed in that
+  column:
+
+    branch      build       cache       caches      carry       checkout
+    deps        device
+    devices     error       failed      findings    fingerprint gems
+    install     installs    ip.txt      lan         launch      lease
+    lock        log
+    logs        meaning     metro       pods        port        prebuild
+    project     readiness   ready       remedy      removed     resolved
+    result
+    services
+    setting     settings    setup       state       stats       stop
+    storage     swap        verify      version     workspace
+
+  \`app\` and \`compilation cache\` join them in the stdout block a successful
+  run ends with. When a native build runs, its compilation-cache result is
+  printed once as a \`cache\` progress line as soon as the build returns,
+  including a failed build. It survives a later install or launch failure.
+  The stdout \`compilation cache\` line is only for an artifact-cache hit
+  (compilation did not run). A line states a fact; the reason a fact matters
+  lives in this guide, not in the run output. Both platforms use the
+  same words, so \`build       ok (51.8s)\` and
+  \`launch      com.example.app (2s)\` read the same on iOS and Android; the
+  artifact name is in the \`--json\` payload.
+
+  A step that costs real time is named and timed, including the step that
+  creates or reconciles the owned device:
+
+    device      stim-app-412 (BF2A..) created (2m14s)
+
+  On iOS that step does not wait the boot out. It creates the simulator, asks
+  it to boot, and hands the wait back, so the run fingerprints the native
+  inputs and resolves the build cache while \`simctl bootstatus\` is still
+  running; it joins the boot before it installs anything. The
+  \`device ... booted\` and \`fingerprint ...\` lines each report their own
+  elapsed time, and those two overlap -- adding every line up overstates the
+  run.
+
+  A step that is still running heartbeats every 30 seconds, on the 30-second
+  grid, so the values read 30s, 1m00s, 1m30s and never repeat. A heartbeat
+  reuses its phase's label and column and names what the phase is doing, never
+  the build tool's own last line -- that transcript is in the build log
+  (\`logs --source build\`):
+
+    build       still compiling (1m00s of ~3m10s)
+    build       still compiling (4m00s, usually ~3m10s)
+    build       still compiling (1m00s)
+    pods        still installing (1m30s of ~1m40s)
+    build       waiting on /w/app-411 (pid 41233, 1m30s elapsed)
+
+  The \`~\` value is an estimate, never a countdown; the third line is a
+  project with no record to estimate from yet. \`guide facts stats\` says where
+  the number comes from.
+
+  The lifecycle commands use the same column. \`worktree warm\` reports
+  copied and kept entries on stderr, with empty stdout:
+
+    carry       copied node_modules from /w/main
+    carry       complete: 1 ignored entries copied, 0 kept, 0 failed
+
+  \`--refresh\` always prints a \`lock\` line, then its own facts, one per
+  step, before those. A plain warm prints the \`lock\` line only when its copy
+  actually waited for another warm:
+
+    lock        acquired (waited 12s for stim worktree warm --refresh pid 41233)
+    checkout    janic/wip 2 commits behind origin/janic/wip -> fast-forwarded to 4b81e0c
+                not the default branch (main); worktrees seeded from this copy
+                carry janic/wip's dependencies
+    deps        source /w/main: pnpm-lock.yaml unchanged -> skipped
+    pods        source /w/main/apps/mobile: ios/Podfile.lock changed -> pod install (1m12s)
+
+  A wait reports how long this caller has waited and names the holder:
+  \`lock        waiting 40s for stim worktree warm --refresh (pid 41233)\`.
+
+  \`start\` names the port, the supervisor mode and its pid on one line
+  (\`metro       starting on port 8083 (expo-child, supervisor pid 13724)\`),
+  and \`stop\` reports what it released:
+
+    stop        supervisor pid 34856
+    stop        collector ios pid 45268
+    device      shut down stim-e2e-2
+    port        released 8084
+
+  \`worktree remove\` reports itself the same way: the branch decision, the
+  owned device, any released device lease, and this workspace's own state
+  directory, each on its own line. Nothing prints on stdout; even the removed
+  path is on stderr:
+
+    branch      kept app/412 (Stim did not create it)
+    device      parked stim-parked (iPhone 17 26.5) 9c1f (9C1F..)
+    lease       released the ios lease on 00008101-000A10913C89001E (it ran until 14:32:10)
+    workspace   removed /w/.stim/workspaces/3f9c2a
+    removed     /w/app-412
+
+  Removal works with any linked worktree, whether warmed or not, and does not
+  require a Stim registry entry. Git-created branches are kept. An existing
+  Stim ownership record permits deleting a branch only when it has no unique
+  commits; otherwise the command reports why it kept it. On the source checkout,
+  \`worktree remove\` reclaims only the
+  environment -- the same \`device\`, \`lease\` and \`workspace\` lines, ending
+  with a sentence instead of a \`removed\` line, because the checkout itself
+  is never touched: \`Reclaimed the environment; the working tree stays (it
+  is the source checkout).\`
+
+  A GAP BETWEEN HEARTBEATS IS NOT A HANG. Stim runs device tools
+  synchronously, so a long \`simctl\`, \`adb\` or copy call holds the timer
+  until it returns; the next heartbeat then lands on the grid, which is why an
+  elapsed value can jump. Read the phase lines, not the wall clock, before
+  killing a run.`
+			},
+			pool: {
+				summary: "parked and adopted simulators: what park and adoption clear or keep, the model and runtime match",
+				body: () => `  THE SIMULATOR POOL
+  \`worktree remove\` PARKS this workspace's owned simulator instead of
+  deleting it, and the next workspace that wants the same model and runtime
+  ADOPTS it. A simulator that has booted before boots in about 9s; a freshly
+  created one costs about 30s, and \`simctl erase\` puts most of that back, so
+  a parked simulator keeps its app installed and is cleaned in pieces:
+
+    at park       shut down, the app's data cleared on disk (Documents,
+                  Library, tmp, SystemData: NSUserDefaults, AsyncStorage,
+                  SQLite), renamed \`stim-parked (<model> <runtime>) <4 hex>\`
+    at adoption   renamed for the adopting workspace, then, inside the boot
+                  the run pays anyway, \`simctl privacy reset all\` and
+                  \`simctl keychain reset\`; at install, every OTHER app the
+                  previous workspace left is uninstalled
+
+  A parked simulator KEEPS its system state: pasteboard, Safari data, photos,
+  contacts, calendars, installed profiles, Simulator settings, app-group
+  containers, and device-level defaults. Isolation covers the app's data, the
+  privacy grants, the keychain and the installed apps -- not a clean system
+  image. Set the bound to 0 when a project needs one.
+
+  Adoption matches the device type AND the runtime EXACTLY: a ticket that asks
+  for an iPad never gets an iPhone, and a request for iOS 18.5 never gets 26.5.
+  No match creates a new simulator, as before. After a runtime upgrade the
+  parked simulators on the old runtime are never adopted; they leave by
+  eviction or \`gc --delete\`.
+
+  The pool targets at most \`pool.iosParkedMax\` simulators (default 3, about
+  2.5 GB each). Past that the oldest parked one is deleted:
+
+    device      parked stim-parked (iPhone 17 26.5) 9c1f (9C1F..)
+    device      deleted stim-parked (iPhone 17 26.5) 4b02 (pool over 3)
+
+  A failed or unverifiable deletion keeps its ownership record so \`gc\` can
+  retry it. The reported pool can temporarily exceed the bound rather than
+  orphaning a simulator.
+
+  and an adopting run says so where a plain boot would say \`booted\`:
+
+    device      stim-app-412 (iPhone 17 26.5) (9C1F..) adopted (11s)
+
+  That time includes the two resets, so it runs longer than a plain boot.
+  \`stim status\` prints one line while the pool is not empty:
+
+    pool: 2 parked iOS simulators (max 3)
+
+  \`stim gc\` reports the pool, and \`stim gc --delete\` empties every entry
+  it can re-verify:
+
+    Parked simulators (2, 5.1 GB):
+      ios stim-parked (iPhone 17 26.5) 9c1f (9C1F..) iPhone 17 26.5 parked 3d ago 2.6 GB
+                  --delete attempts every parked simulator and keeps failures.
+
+  If simulator listing or deletion fails, \`gc --delete\` reports the failure
+  and keeps that entry. It never turns an unverified absence into a dropped
+  ownership record.
+
+  That deletion works even under a redirected \`STIM_HOME\`, where the sweep
+  for unlisted \`stim-\` devices stays refused: a parked record in THIS config
+  proves that simulator is Stim's and parked by this home. \`stop\` never
+  parks -- it shuts the owned simulator down and keeps it assigned. Neither
+  does \`gc --delete\`, which is deleting what it finds.
+
+  ANDROID EMULATOR POOL
+  Android uses the same bounded park/adopt lifecycle, with
+  \`pool.androidParkedMax\` (default 3) or STIM_POOL_ANDROID_PARKED_MAX.
+  A redirected STIM_HOME disables parking unless that environment override
+  is set. Zero disables parking and adoption. \`stop\` keeps the assignment;
+  \`worktree remove\` parks eligible AVDs, and \`gc --delete\` empties the pool.
+
+  Adoption matches the system image, data partition size, and the creation
+  settings from android.avdConfig / android.avdConfigFile. The AVD keeps its
+  original stim-<label> name so its Quick Boot snapshot can survive reuse.
+  Normal desktop boots allow Quick Boot; headless Linux disables snapshots.
+  Incompatible AVDs stay parked until eviction or GC. AVDs created by older
+  versions without a recorded creation configuration are deleted at removal.
+
+  When a fresh AVD's preferred name belongs to another workspace or a parked
+  entry, Stim adds a short suffix instead of taking over that device. Always
+  use the actual device name and serial reported by the platform command.
+
+  Android cleanup happens AFTER boot, before install or launch: \`adb shell
+  pm clear\` clears the adopting app's data while retaining its APK, and
+  other third-party apps are uninstalled. If ADB goes offline or closes the
+  connection, Stim waits for boot readiness and retries cleanup for up to 30
+  seconds, verifying the same owned AVD before each destructive command.
+  Failed cleanup blocks launch and remains pending for a retry. The installed APK's SHA-256 must match the
+  requested artifact before Stim skips installation; a package name or cache
+  key alone is insufficient, including for release builds with swapped JS.
+  If the retained APK has a conflicting signer or version, adoption uninstalls
+  it and retries installation. Adoption stays pending until installation succeeds.
+
+  Parked AVDs retain app data until adoption. System apps, shared storage,
+  accounts and device settings also remain: this is not a factory reset.
+  Set the Android bound to 0 when a project needs a fresh device. Status lists
+  parked Android emulators; GC reports their system image, age and disk size.
+`
+			},
+			builds: {
+				summary: "optional cache warm-up, build optimizations, fingerprints, .fingerprintignore, install unchanged, runtime state",
+				body: () => `OPTIONAL CACHE WARM-UP FOR REPEATED NATIVE WORK
+  When several native worktrees are coming, build the source checkout once to
+  seed the shared caches before warming the linked worktrees. Skip this extra
+  build for one-off or JavaScript-only work. For local simulator or emulator
+  work, run these commands in the source checkout's app directory:
+
+    stim doctor --platform ios        # or: --platform android
+    stim start
+    stim ios                          # or: stim android
+    stim stop
+
+  Follow the normal ownership and consent rules in guide agent.
+
+IOS SCHEME SELECTION
+  Pass \`stim ios --scheme "App Staging"\` to select an exact shared Xcode
+  app scheme. Unknown names refuse with the available choices. This is the
+  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:
+  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.
+
+  Explicit schemes have separate artifact keys, shared-build locks, and Xcode
+  build directories. Stim identifies the resulting application from Xcode's
+  resolved build settings, even when the scheme and product names differ;
+  ambiguous products refuse rather than installing another app. Local and
+  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.
+
+AN ARTIFACT THE DEVICE ALREADY HOLDS IS NOT INSTALLED AGAIN
+  Both platforms store the artifact verbatim, so its hash is its identity.
+  Before installing, Stim hashes the artifact it is about to install and the
+  one the device already has -- \`pm path\` then \`sha256sum\` on Android, the
+  \`simctl get_app_container\` bundle on iOS. Byte-identical means the install
+  is skipped. The phase still reports the cost of proving that identity, but
+  avoids the ~43s a 400MB APK can cost to copy and install over USB.
+
+    install     unchanged (emulator-5584 already has this build) (0.4s)
+
+  On iOS the install line names the identity proof separately from the Expo
+  dev-client preference writes, so a slow simulator command is never charged
+  to an install that did not run:
+
+    install     unchanged (stim-app already has this build) (0.4s)
+    install     dev client prepared (0.9s)
+
+  The skip needs PROOF. A package that is not installed, a split install, an
+  image without \`sha256sum\`, and any adb or simctl failure all read as
+  "cannot determine", and the run installs exactly as it always did. A release
+  run swaps this workspace's JS into a COPY of the artifact, which is a
+  different artifact and is therefore always installed.
+
+  \`--json\` carries installSkipped so a caller can tell a skipped run from an
+  installed one.
+
+RUNTIME STATE AND BUILD INPUTS
+Runtime state is stored outside the project tree under
+$STIM_HOME/workspaces/<project>--<digest>/ (default ~/.stim/workspaces/).
+The aggregate run counters \`stats\` prints live beside it in
+$STIM_HOME/stats.json, one bucket per project and platform plus a machine-wide
+one; nothing per run is kept there.
+No .gitignore entry is created or required.
+Native preparation can change project files: expo prebuild generates native
+sources, and pod install can update Podfile.lock. Review those changes before
+committing. The shared caches need no project-file edits. The defaults below can be changed
+with machine or project optimization settings; see \`guide settings\`:
+
+  ios      xcodebuild carries COMPILATION_CACHE_ENABLE_CACHING, a shared
+           COMPILATION_CACHE_CAS_PATH and a clang prefix mapping of this
+           workspace's root, so compiled output crosses worktrees with no
+           Podfile post_install block. Xcode 26+ only, and skipped entirely
+           when the project configured ccache (the two defeat each other).
+  android  gradlew carries --build-cache, so task outputs cross worktrees with
+           no org.gradle.caching=true in gradle.properties. Debug builds also
+           carry -PreactNativeArchitectures=<target ABI>, using the owned
+           emulator system-image ABI or the physical device's primary ABI.
+           Unknown targets and Release builds stay universal.
+  ccache   the same gradlew run carries an absolute
+           CMAKE_C_COMPILER_LAUNCHER / CMAKE_CXX_COMPILER_LAUNCHER plus
+           CCACHE_DIR, CCACHE_BASEDIR, CCACHE_NOHASHDIR, CCACHE_SLOPPINESS
+           and CCACHE_MAXSIZE whenever a ccache binary is on PATH, so the C++
+           objects cross worktrees as well. Nothing is set when ccache is
+           absent, or when the project passes a CMake compiler launcher of
+           its own.
+  start    the dev server gets a shared Metro FileStore APPENDED to whatever
+           the project configured -- in-process on a bare project, and through
+           Expo's config override on SDK 54+. Expo SDK 53 and older use their
+           normal Metro cache. Turn it off machine-wide with
+           { "optimizations": { "metroSharedCache": false } } in
+           ~/.stim/config.json; see \`guide settings\`. A project that calls
+           \`sharedCacheStores()\` from @stim-cli/metro in its own metro
+           config also gets the \`cache.provider\` tier behind that store.
+
+Every Stim Android build uses a CMake staging profile, including the default
+ccache mode. The first run with this layout configures a separate build tree;
+changing modes selects another profile. See \`guide settings\` for cleanup.
+
+Each reports its cache setup. \`stim doctor\` checks missing or stale setup
+when a build is blocked or slow. It reports what Stim cannot handle itself
+(a missing dev client, ccache absent from PATH or a .cxx that predates the
+launcher, a fingerprint no fresh worktree reproduces, a provider on a key this
+SDK ignores) and settings for builds outside Stim.
+
+IOS DEBUG ARCHITECTURES
+Doctor reads Xcode's effective Debug simulator settings for app targets and
+generated Pods, including xcconfig inheritance and SDK-specific overrides.
+It warns when ONLY_ACTIVE_ARCH=NO leaves multiple architectures after ARCHS,
+VALID_ARCHS, and EXCLUDED_ARCHS are combined. A Podfile post_install helper can
+cause this even when the app target already uses ONLY_ACTIVE_ARCH=YES.
+Review that override for local Debug builds; preserve intentional Release and
+distribution settings. Regenerate Pods through the project's normal workflow
+after changing a helper, then rerun \`stim doctor --platform ios\`.
+Doctor never evaluates Podfile Ruby, installs Pods, or changes architecture
+settings, including under --fix. This inspection runs only in doctor, with
+30 seconds per Xcode query and 60 seconds total. Missing generated projects,
+failed metadata queries, and unresolved settings produce an unverified note
+rather than an architecture warning or a verified clean result.
+
+WHY ANDROID NEEDS CCACHE, AND WHAT IT COSTS
+Every AGP CMake task is uncacheable by Gradle, so --build-cache serves not one
+C++ compile. Without a launcher a fresh worktree recompiles every translation
+unit, which on a React Native app with native modules is most of a first build.
+The shared objects live at $STIM_HOME/ccache (default ~/.stim/ccache), which is
+registered for \`gc\` and prunes itself at CCACHE_MAXSIZE.
+
+CCACHE_BASEDIR rewrites paths under the workspace root relative to the compile
+directory and CCACHE_NOHASHDIR keeps the working directory out of the hash;
+together they are what lets an object built in one worktree match in another.
+The trade-off is the same class as the iOS CAS one: an object reused from
+worktree A carries A's directory as its DWARF comp_dir, so a debugger stepping
+into reused C++ resolves sources against that path.
+
+When Stim supplies ccache, its Gradle init script defaults Android app and
+library CMake builds to CMAKE_DISABLE_PRECOMPILE_HEADERS=ON. PCH inputs can
+retain a previous worktree's paths even with upstream timestamp fixes, causing
+the header and its consuming objects to miss. Compiling ordinary headers
+instead favors reuse across worktrees at the cost of a slower cold C++ build.
+This does not edit dependency sources or change iOS builds. Without Stim's
+ccache setup, auto PCH behavior is unchanged. Explicit optimizations.android.pch
+on/off applies with any compiler cache selection. A module with an explicit
+CMAKE_DISABLE_PRECOMPILE_HEADERS argument in its default config, build types,
+or product flavors keeps that choice; CMake target-level PCH overrides also
+take precedence. Direct Gradle builds do not receive Stim's init script.
+
+EXPERIMENTAL ANDROID CAS
+optimizations.android.compilerCache="cas" with android.casToolchain under the
+same optimizations object selects a private Apple Clang toolchain manifest
+on macOS. STIM_ANDROID_CAS_TOOLCHAIN also selects CAS in auto mode. It retains
+PCH and replaces the ccache setup for that invocation.
+Compiler results live under $STIM_HOME/android-cas/<toolchain-id>; APK cache
+keys include that ID. This is a development prototype requiring a compatible
+linker and NDK copy, not an automatically installed backend. Because the
+manifest lives outside the repository it can rot: when the setting holds any
+value that is not an absolute path, or the manifest it names is missing or
+unreadable, the build warns once naming the setting and the file it came from,
+then compiles through the cache the selection leaves -- ccache, or none when
+compilerCache is none. It never refuses. See
+https://stim.appandflow.com/docs/android-cas for setup, evidence, and limits.
+Compiler/PCH modes have separate generated directories under each module's
+.cxx/stim-<profile> (or custom staging root). Switching modes in Stim selects
+the matching directory; direct Gradle builds keep their own configuration.
+Generated CAS directories still depend on Stim's environment and adapter paths.
+
+For older, unprofiled builds, the launcher persists in the project. AGP writes
+it into each
+.cxx/**/CMakeCache.txt on the first configure, so a plain \`./gradlew\` in that
+checkout also compiles through ccache -- and a .cxx configured BEFORE the
+variables existed can keep compiling without them until it is cleared once.
+\`stim doctor\` reports stale configurations in this checkout's app and installed
+native modules. Stop native builds, then run \`stim doctor --fix --platform android\`:
+it removes only affected ignored, untracked legacy .cxx configurations and
+reruns the diagnostics. Managed profiles and disabled compiler caches are
+left alone. A cas selection Stim cannot use resolves to ccache, so that
+checkout's legacy configurations become eligible for the same repair. A config
+the repair cannot read repairs nothing. The next build recreates legacy output. It refuses directories
+outside the checkout and configured custom launchers. Shared ccache entries and
+source files are preserved. Its cache-lock check cannot detect --no-build-cache,
+release-swap fallback, or direct Gradle builds; stop all native builds and keep
+them stopped until repair finishes.
+Run it before copying the checkout into worktrees.
+
+THE BUILD CACHE HAS THREE LEVELS
+  1. Stim's own, on this machine: a directory under ~/.stim shared by
+     every worktree, keyed on the @expo/fingerprint hash of the native inputs.
+     Free, instant, offline, and the only level a project without any
+     provider has.
+  2. The project's own cache provider, on ANY project including bare React
+     Native: \`cache.provider\` in the settings, a module implementing the
+     @stim-cli/cache contract (see \`guide settings\`). Consulted only when
+     level one misses, and its hit is stored into level one before install.
+     The same contract serves the Metro transform cache.
+  3. On an EXPO project only, the provider the project ALREADY configured for
+     Expo (\`expo.buildCacheProvider\` -- "eas", or a module of its own).
+     Consulted only when levels one and two miss, bounded so a slow or expired
+     remote cannot stall the loop, and a hit is copied into level one on the
+     way past so the next workspace on this machine gets it for free. After a
+     build, the result is stored locally AND handed to both providers, which
+     run independently. An ABI-targeted Android Debug build skips this Expo
+     tier because its run-options contract cannot distinguish ABIs; levels one
+     and two remain ABI-keyed and active.
+
+  Stim never configures a provider and never suggests changing one: a
+  project without one is a perfectly ordinary local-only project (doctor does
+  not ask for one either -- a provider only serves builds run OUTSIDE Stim).
+
+  A provider that fails to load, times out, or errors produces ONE note per
+  failure class and the run continues on the local cache. \`gc\` reports,
+  trims, and clears local caches only: the provider contract has no delete
+  operation, so no local command can remove data a team or CI system shares.
+
+  A MISS explains itself when it can. When this workspace's previous build
+  stored its fingerprint sources beside the cache entry, the fingerprint line
+  gains " -- N sources changed: <up to three paths>", and the full list
+  (capped at 20 names) lands in the build log as a fingerprint_diff record.
+
+  THE KEY CAN MOVE MID-RUN, and the run says so in two facts rather than two
+  explanations. \`expo prebuild\` and \`pod install\` rewrite fingerprinted
+  files while they work, so the run fingerprints again afterwards:
+
+    fingerprint dcbd8d.. -> 6564e2.. (after prebuild, pod install)
+    cache       hit 6564e2.. (post-prebuild/pod install key)
+
+  The first line means the artifact, the \`lastBuild\` record and any remote
+  upload are stored under the SECOND hash -- the one the next run in this tree
+  computes, and therefore the one it looks up. The second line only appears on
+  a tree that was COLD: the first lookup ran on the pre-prebuild hash and
+  could not find an entry another workspace had already stored under the
+  post-prebuild one, so re-resolving under the moved key installs it instead
+  of compiling beside it. No second line means nothing was found there and the
+  run compiles.
+
+  If the iOS fingerprint after prebuild or pod install is unavailable, Stim
+  installs the build but skips local storage and remote uploads. fingerprint
+  and cacheKey are null in the result and lastBuild; the old key is not reused.
+  Android does the same if its post-Gradle fingerprint cannot be computed.
+  These null fields mean unavailable cache information, not an install failure.
+
+WHAT MAKES THE CACHE ACTUALLY HIT: .FINGERPRINTIGNORE
+  Every entry is keyed on what the tree hashes, so two workspaces share an
+  entry only when they hash alike. A file that changes without changing the
+  BUILD is what breaks that, and it fails silently -- a cache that never hits
+  looks exactly like a cache that is not there.
+
+  Stim ignores two paths a fresh checkout never has and no native build reads:
+  android/local.properties and android/.idea. A project does not repeat those.
+  Everything else is the project's call, including a lockfile whose checksums
+  embed machine paths -- ignoring a path any project might read turns a slow
+  build into a wrong one.
+
+  A linked native library (a \`link:\` or \`file:\` dependency, or a workspace
+  symlink) brings its checkout's .git into a directory the fingerprint hashes
+  whole; Git rewrites that metadata on every commit, checkout, or worktree, so
+  workspaces rarely agree. \`stim doctor\` names the entries to ignore when the
+  native build does not read Git state: the .git path as the fingerprint sees
+  it and its /**/* form, which is what skips a .git directory's contents.
+  Ignore those entries only, never the package.
+
+  \`.fingerprintignore\` at the project root (same syntax as .gitignore) is the
+  answer. Put in it only what genuinely cannot change the native build: a
+  generated report, a local env file, a lockfile whose checksums embed absolute
+  machine paths (\`ios/Podfile.lock\` is the usual one -- pod checksums can bake
+  in a machine path, and \`pod install\` rewrites it on a plain re-install).
+  Never ignore a real native input -- a Podfile, a gradle file, the app config
+  -- to force a hit: that trades a slow build for a wrong one.
+
+  \`stim doctor\` measures this directly rather than reading the file: it
+  fingerprints HEAD in a temporary clean worktree, compares, and reports a
+  mismatch naming the differing sources. Untracked, non-gitignored files under
+  ios/ or android/ count too -- they are hashed like any other source, so a
+  stray file there moves the key on your machine and nowhere else.`
+			},
+			concurrency: {
+				summary: "waiting on another workspace's build, --no-build-cache, concurrency.maxBuilds and maxDevices",
+				body: () => `ONE COMPILE PER FINGERPRINT, ACROSS EVERY WORKSPACE
+  The cache makes the SECOND workspace on a commit free -- but only once the
+  first has finished. Three agents starting within the same minute all miss it,
+  and without this all three compile the same app at once, fighting for the
+  same cores. So when both cache levels miss, the run takes a LOCK on
+  <fingerprint, platform> (a directory under ~/.stim/build-locks). Exactly
+  one workspace compiles; the others print
+
+    build       /w/app-412 is already building a3f9b1.. (pid 41233) -- tail ...
+    build       waiting on /w/app-412 (pid 41233, 4m elapsed) -- tail ...
+    build       waited 12m41s for /w/app-412's build -> installed from cache
+
+  and install the artifact the builder stored. They report cacheHit: "local"
+  plus waitedForBuild: { pid, ms }.
+
+  Native preparation can move the builder's cache key. A released lock with no
+  artifact at the original key does not prove the build failed. The waiter
+  rechecks after its own native preparation; a matching post-preparation cache
+  hit retains waitedForBuild. Artifacts remain stored only under their final
+  fingerprint, never under the old key.
+
+  Nothing can deadlock on it. The lock records the holder's process IDENTITY,
+  so a builder that crashes, is killed, or whose build simply fails frees it:
+  the waiters see a released lock with no artifact, and one of them takes over
+  and builds. A recycled pid reads as a gone builder, and a builder busy in a
+  long synchronous tool call reads as live -- age is never a reason to take a
+  lock. The one state that cannot be decided (a truncated claim, an identity
+  token that does not decode) is STIM_CLAIM_REFUSED: Stim names the claim and
+  the command that removes it rather than guessing. A process whose own identity
+  cannot be captured takes no lock and no slot, and refuses with
+  STIM_CLAIM_UNAVAILABLE rather than building unprotected. The
+  other waiters keep waiting for that holder. All replacement builders share
+  one ~90-minute deadline, including lock acquisition between waits; reaching
+  it returns STIM_BUILD_WAIT_TIMEOUT naming the current holder and lock.
+
+  --no-build-cache looks nothing up -- not the local cache, not either
+  provider -- and takes no lock and never waits, because it asked for a compile
+  of its own. It still STORES the result, over the entry it was told not to
+  trust, and still uploads it. Use it when a cached artifact is suspect; the
+  --json payload reports cacheSkipped: true so a caller can tell that run apart
+  from a plain miss.
+
+OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
+  Stim imposes NO limits of its own: unset is exactly the behaviour above --
+  every build compiles, every device boots. When a machine cannot host as many
+  parallel builds or booted simulators as there are agents, two MACHINE-level
+  caps rein it in. They live under a top-level \`concurrency\` key in
+  ~/.stim/config.json (not per-project -- the resource being shared is the
+  machine's), and STIM_MAX_BUILDS / STIM_MAX_DEVICES override the file.
+  Absent, 0, or any non-positive value means NO enforcement.
+
+    concurrency.maxBuilds   how many builds COMPILE at once. It is a semaphore
+                            of N slots (~/.stim/build-slots). A run takes a
+                            slot AFTER the single-flight lock -- a workspace
+                            waiting to install another's identical artifact
+                            never burns a slot -- so it caps distinct compiles,
+                            not waiters. A full slate WAITS (this is batch work),
+                            printing the same kind of progress line the build
+                            lock does, and a dead builder frees its slot within
+                            a poll (process identity, like the lock).
+
+    concurrency.maxDevices  how many Stim-owned devices are BOOTED at once. Checked
+                            at device time, before a sim is created or booted.
+                            At the cap, a NEW device is REFUSED with
+                            STIM_AT_CAPACITY (interactive-shaped: it does not
+                            queue). A workspace whose own device is already
+                            booted is never refused.
+                            See \`guide errors STIM_AT_CAPACITY\`.
+
+  \`stim doctor\` prints one note echoing the caps and the current live count,
+  but ONLY when a cap is set. \`stim gc\` reports stale build slots the way it
+  reports stale build locks, and \`gc --delete\` clears them. There is no
+  \`stim config\` command: set these by editing ~/.stim/config.json or via
+  the two env vars (see \`guide settings\`).`
+			},
+			options: {
+				summary: "every flag per command, Android variants and flavors, the per-run simulator model, runtime and system image",
+				body: () => `THE OPTION SURFACE, IN FULL
+  start           --json --wait <seconds> --remote --reset-cache
+  ios             --json --no-metro-check --no-build-cache --scheme <name> --configuration <name> --device-type <name> --runtime <version> --device [udid] --wait <seconds> --no-wait --remote <proxy|eas>
+  android         --json --no-metro-check --no-build-cache --variant <name> --system-image <id> --device [serial] --wait <seconds> --no-wait --remote <proxy|eas>
+  reload          [ios|android] --json
+  device          lock <ios|android> [id] --for <duration> --wait <seconds> --json;
+                  unlock [ios|android] --json
+  logs            --source --level --since --grep --tail --follow --errors --json
+  stop            --json
+  status          --json          (already machine-wide)
+  stats           --json          (this project and machine-wide)
+  doctor          --json --fix --platform <ios|android>
+                                  (--platform keeps shared checks and filters native findings)
+  gc              --delete --older-than <days> --cache <name|all>
+  worktree warm    --refresh; remove [path] --force
+
+  That is the whole surface today, and it is deliberately small. It can grow
+  when a flag is genuinely the best answer -- but project-specific knowledge
+  (release builds, variants, device targets) belongs in a script the repo owns,
+  not in a flag here.
+
+  \`stim worktree warm\` takes one flag, \`--refresh\`. Run it anywhere inside
+  the current linked worktree to copy missing ignored entries from its source
+  checkout, regardless of either branch's HEAD. Both roots must be registered
+  worktrees of the same Git repository; the source checkout must be available.
+  Running it in the source checkout refuses.
+
+  \`--refresh\` WRITES TO THE SOURCE CHECKOUT before the copy, which is why it
+  is opt-in: it fetches, fast-forwards whatever branch is checked out there to
+  its \`@{upstream}\`, and installs what the new commits moved. It refuses a
+  source checkout it cannot move -- uncommitted changes to tracked files or a
+  rebase or merge in progress (STIM_MAIN_DIRTY), a detached HEAD
+  (STIM_MAIN_DETACHED), or a branch that is both ahead and behind
+  (STIM_MAIN_DIVERGED) -- and each refusal names the git line that clears it.
+  Untracked files are not a reason to refuse. A branch with no upstream is
+  left where it is. A fetch that fails is a fact, not a refusal: the run
+  continues on the local state. It never switches branches, never merges, and
+  never resets; fast-forwarding a feature branch is safe, so it only WARNS
+  that the copy will carry that branch's dependencies. The default branch it
+  compares against is \`worktree.defaultBranch\` in the repository-root
+  .stim.json, else \`git symbolic-ref --short refs/remotes/origin/HEAD\`;
+  when neither answers it says so and makes no warning.
+
+  Dependencies install where the lockfile is, which in a monorepo is the
+  repository root, when the lockfile moved or nothing is installed. Pods run
+  for the app the command was invoked from, and only that app, when its
+  ios/Podfile.lock moved or ios/Pods/Manifest.lock does not match it. Each
+  completed or skipped deps and pods step names its source directory and
+  reason. A failed install refuses with STIM_DEPS_FAILED and nothing is copied.
+
+  An install that did not finish is remembered, and a PLAIN warm reads that
+  before it copies. The refresh records the completed install of the lockfile it
+  read under ~/.stim/warm-installs; a plain warm reads that record after it
+  takes its claim, and refuses with STIM_DEPS_INCOMPLETE, copying nothing, when
+  the unfinished install is of the lockfile as it stands NOW -- otherwise the
+  copy carries a partial node_modules and exits 0, and only the refresh's own
+  terminal ever said the install failed. A record of a different lockfile does
+  not block a copy, and a repository with no record copies exactly as it did
+  before the record existed. The remedy is \`--refresh\`, which reinstalls rather
+  than skipping on the same record, so a refresh killed mid-install -- which
+  writes no failure anywhere -- is recovered the same way a failed one is.
+
+  One lock per repository serialises this, whether or not you pass the flag:
+  \`--refresh\` holds it exclusively, and every copy holds it shared, so a copy
+  can never read a node_modules a refresh is rewriting. Two plain warms of the
+  same repository run together. The lock is keyed on the repository root, so
+  two apps of one monorepo share it. It is the same ownership claim the build
+  locks take: the holder's process IDENTITY decides, so a holder that dies frees
+  it, a recycled pid cannot keep it, and a refresh whose install runs in a
+  spawned process group holds it while that group lives. A wait prints the
+  holder every 30s and gives up with STIM_LOCK_TIMEOUT; a claim Stim cannot
+  resolve refuses with STIM_CLAIM_REFUSED and names the removal rather than
+  waiting on it or removing it.
+  A plain warm that cannot record a claim at all -- an unwritable STIM_HOME, a
+  STIM_HOME on a read-only mount or under a dangling symlink, a STIM_HOME that
+  is a file, or no \`unique-pid\` build for this platform
+  (STIM_CLAIM_UNAVAILABLE) -- says so in one dim line and copies without it,
+  exactly as it did before the lock existed, because a copy only reads.
+  \`--refresh\` refuses instead, because it writes. Before that unsynchronised
+  copy starts, warm still READS the claim set, which needs no claim of its own:
+  if a refresh holds this repository, or a claim in it cannot be resolved, the
+  copy refuses rather than reading a tree that is being rewritten. That read is
+  not a lock, so a refresh that starts after it is not covered; it closes the
+  window in which one is already installing. Closing the rest needs a claim,
+  which is the one thing that state cannot record, so the residual is
+  documented rather than fixed (appandflow/stim#696), as is the
+  \`acquired (waited 0s ...)\` a contended-but-fast wait prints.
+
+  Wait for warm to exit successfully (exit code 0) before running start,
+  ios, android, or a dependency install in that worktree. If a shell tool
+  yields a running session or job ID, poll or wait for completion; empty
+  stdout or a returned job ID does not mean the copy has finished. Concurrent
+  writes to the destination are unsafe: existing entries are checked before
+  copying, not during it. Do not edit files, run another warm, or start any
+  other writer in that worktree until warm finishes. Concurrent files can be
+  overwritten or removed.
+
+  Warm copies installed dependencies, Pods, native output, and other ignored
+  paths eligible under the source checkout's Git ignore rules, including .env
+  and local configuration. The source's nonempty
+  .worktreeexclude replaces its resolved worktree.exclude setting. Nested
+  registered worktrees, .DerivedData, and android/build/generated/autolinking
+  caches are excluded, including in nested apps. Gradle regenerates autolinking
+  for the destination checkout on its next build. Warm also skips paths
+  overlapping a nested destination worktree or below a symlink ancestor.
+
+  Warm copies directly into the destination, without intermediate staging.
+  Keep the source checkout and the linked worktree on the same volume to
+  retain copy-on-write cloning where supported. Cross-volume copies require
+  full file data; doctor reports that cost. STIM_TMPDIR and machine tempDir do
+  not affect warming.
+
+  Existing entries, including dangling symlinks, stay untouched. An existing
+  ignored directory such as node_modules is skipped WHOLE; missing children are not
+  filled in. Warm does not copy tracked changes, switch branches, or build,
+  and it installs dependencies only under \`--refresh\`, in the source checkout. stdout stays empty; stderr reports copied, kept,
+  and failed entry counts. A copy failure exits 1 and reports incomplete;
+  files copied before a failure remain. Inspect the named failed entry
+  before retrying: a partially copied directory will be kept on the retry.
+  A completed copy is not proof that dependencies match this branch. Follow
+  any lockfile remedies before building, and install missing dependencies
+  with the project's package manager when the source has none to copy.
+
+  \`android --variant <name>\` selects the gradle variant to assemble and
+  install on a project with product flavors -- \`--variant productionDebug\`
+  runs \`assembleProductionDebug\`, finds the APK in apk/production/debug/ and
+  keys the build cache on the variant. It overrides the android.variant
+  setting (see \`guide settings\`), which is the app-level default; unset,
+  the plain \`assembleDebug\` flow is unchanged. The --json payload's
+  \`variant\` field reports what was built (null for the default).
+  When neither is set and android/app/build.gradle declares more than one
+  product flavor, \`android\` refuses BEFORE gradle runs and names the debug
+  variants to choose from, because \`assembleDebug\` would build every flavor
+  and leave nothing to pick from. That parse is best-effort: flavors built
+  from a variable, a loop, or an applied script are not detected, and such a
+  project builds as before.
+
+  \`ios --device-type <name>\` and \`ios --runtime <version>\` choose the
+  MODEL and the iOS version of the simulator this workspace owns --
+  \`--device-type "iPad Pro 13-inch (M4)" --runtime 18.5\` is how a ticket that
+  says "happens on iPad on iOS 18.5" gets reproduced without writing a
+  \`.stim.json\`. \`android --system-image <id>\` is the Android half, taking
+  the sdkmanager package id
+  ("system-images;android-36;google_apis;arm64-v8a"). Each overrides its
+  setting (ios.deviceType, ios.runtime, android.systemImage) for that one
+  invocation, exactly as \`--configuration\` overrides ios.configuration.
+
+  A name that is not INSTALLED on this machine refuses with STIM_BAD_ARG
+  before anything is created, and the message lists the installed names, so a
+  wrong guess is one command, not a created simulator. A blank value is the
+  same refusal.
+
+  What counts as installed for \`--device-type\` is what an installed RUNTIME
+  can create, not what \`xcrun simctl list devicetypes\` prints: that table
+  also names watchOS, tvOS and visionOS models, and older iPhones no current
+  runtime supports, none of which \`simctl create\` would accept. So the
+  refusal lists the models the installed runtimes offer -- narrowed to the one
+  runtime when \`--runtime\` also resolved, which is what catches a pair like
+  \`--device-type "iPhone 8" --runtime 26.5\` that each half would pass alone.
+  \`--runtime\` takes a version (\`26.5\`) or a runtime's full name
+  (\`iOS 26.5\`), exactly; no prefix or suffix matches.
+
+  These flags describe a device that does not exist yet. When this workspace
+  ALREADY owns a simulator and \`--device-type\` names a different model,
+  Stim refuses rather than silently booting the wrong one: reap the current
+  sim with \`stim worktree remove\` (or \`stim gc --delete\`), then run
+  \`stim ios\` again to create the requested one. \`--runtime\` and
+  \`--system-image\` apply at creation only, so an existing device keeps the
+  version it was made with. The --json payload reports what was actually
+  used: \`deviceType\` and \`runtime\` on iOS, \`systemImage\` on Android,
+  read from the device itself, so a settings-driven run reports them too.`
+			},
+			devices: {
+				summary: "ios --device and android --device on a phone: what the run skips, signing, the LAN wiring, the collector",
+				body: () => `  \`android --device [serial]\` installs and launches on a physical device
+  connected to this machine instead of this workspace's owned emulator. With
+  no serial it takes the first device it can lease (\`guide lifecycle lease\`).
+  It cannot be combined with --remote.
+
+  A \`--device\` run LEASES the device from just after the build until it
+  exits, so a second workspace cannot install over it mid-run
+  (\`guide lifecycle lease\`).
+
+  The build, the fingerprint, the build cache and the Metro port gate are
+  unchanged. What is skipped is everything that manages an owned device:
+  no capacity check, no AVD creation, no boot wait, and no owned-device
+  registry entry. The app is pointed at
+  localhost:<port>, which the adb reverse serves, instead of the emulator's
+  10.0.2.2. Stim never creates, boots, shuts down, or deletes hardware.
+
+  \`ios --device [udid]\` selects a connected iPhone, the same way
+  \`android --device\` selects a connected phone: with no UDID it takes the
+  first device it can lease (\`guide lifecycle lease\`), and an iPhone
+  that is unpaired or has Developer Mode off is refused with the fix. It
+  cannot be combined with --remote, and it never creates, boots, or deletes
+  hardware -- there is no capacity check, no simulator creation, no boot wait,
+  and no owned-device registry entry. Like
+  \`android --device\`, it leases the phone for the run
+  (\`guide lifecycle lease\`).
+
+  \`stop\` releases this workspace's leases and stops its log collectors.
+  On a physical iPhone that also closes the app, because its collector owns
+  the devicectl launch session. \`gc --delete\` removes expired lease files;
+  neither command shuts down the phone or uninstalls the app.
+
+  A device build is LOCAL-TIER ONLY. Its cache key is
+  \`<fingerprint>-<configuration>-device\`, so a device app can never collide
+  with the simulator one, and neither the build-cache provider nor the Expo
+  remote cache is read or written on a \`--device\` run: every entry they hold
+  is keyed for the simulator, so consulting them would either install a
+  simulator slice on a phone or publish an iphoneos app under a key simulator
+  builds resolve.
+
+  THE BUILD is the \`iphoneos\` slice for the selected phone -- \`-sdk
+  iphoneos\`, the project's own signing settings, no signing flags on the argv.
+  It is installed with \`devicectl device install app\` and launched with
+  \`devicectl device process launch\`. Every device install is SIGNED, Debug
+  included, so the signing gate runs before it: the app's own
+  embedded.mobileprovision must be unexpired and must name this phone, and when
+  Stim modifies the bundle the identity that profile names must be in this
+  machine's keychain (see \`guide errors STIM_NO_PROFILE\`). A gate refusal on
+  a CACHED app falls back to a full build; on a freshly built one it exits on
+  its own code, because building again would produce the same app.
+
+  DEBUG REACHES METRO OVER THE LAN, because a phone shares no loopback with
+  the host and USB carries no reverse forward. Stim picks a non-internal IPv4
+  address (en0 first, RN's own order from react-native-xcode.sh), gates it as
+  this workspace's Metro, and then wires the app to it: an expo-dev-client app
+  through the deep link, passed to devicectl as \`--payload-url\` and followed
+  by \`-- -EXDevMenuShowsAtLaunch 0 -EXDevMenuShowFloatingActionButton 0\`,
+  which is how a phone gets what a simulator gets from a defaults write, and a
+  bare app by writing \`<addr>:<port>\` into the app bundle's ip.txt --
+  RCTBundleURLProvider's own mechanism, which honours a colon-bearing value
+  verbatim and never consults the compiled RCT_METRO_PORT. Stim never sets
+  that define: it would put the reserved port into a compiled input and fork
+  the device cache per workspace.
+  ip.txt is a sealed resource, so Stim writes it on a COPY of the artifact and
+  re-seals that copy with \`codesign\`. THE ORDER IS STORE, THEN COPY, THEN
+  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
+  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.
+
+  THE DEVICE LOG COLLECTOR IS THE LAUNCH. \`devicectl\` connects an app's
+  streams only when it is the process that starts the app, so the collector
+  runs \`devicectl device process launch --console --terminate-existing\`
+  itself rather than attaching after the fact the way the simulator collector
+  does. The run then reads the app's pid from the phone's own process list
+  (\`devicectl device info processes\`), because \`--console\` blocks until
+  the app exits and its \`--json-output\` is written only then. That device pid
+  is also what proves a RELEASE launch: a device pid means nothing to the host,
+  so nothing on the host is ever signalled with it. Otherwise the collector is
+  the same process as every other collector -- one per platform per workspace,
+  titled with its --root, killed and replaced on the next \`ios\` run whose pid
+  still proves it is this workspace's, and reaped by \`stop\`. One difference in
+  the ordering: a device run stops the PREVIOUS collector before it installs,
+  not while starting its own, because an upgrade install terminates the running
+  app -- which would end that collector's devicectl non-zero and record a
+  failure for a normal reinstall. Unplugging the phone ends devicectl, which
+  ends the collector: it removes its own registration and exits. A separately
+  held \`device lock\` lease survives collector exit until released or expired;
+  \`gc --delete\` can remove its expired lease file. Whether it closes with collector_stopped or
+  collector_failed follows devicectl's exit code, which no one has watched a
+  cable-pull produce yet. See \`guide logs\` for what the device stream can
+  and cannot carry, and appandflow/stim#179.
+
+  THE APP RUNS FOR AS LONG AS THE COLLECTOR DOES. Because the collector is the
+  launch, the app is attached to it: \`stop\` (and any other end of that
+  collector -- a crash, the host sleeping, the cable coming out) closes the app
+  on the phone. It stays INSTALLED. Collector exit removes the collector's
+  registration, not a separately held device lease; \`stop\` also releases
+  this workspace's leases. See \`guide cleanup collector\`.
+
+  THERE IS NO INSTALL SKIP ON A PHONE. The simulator path skips the install
+  when the device already holds the same bundle byte for byte, which it proves
+  by hashing the installed container; there is no cheap equivalent through
+  devicectl, so a device run always installs. It is an upgrade install: the
+  app's data, and the Local Network permission the phone granted it, survive.`
+			},
+			lease: {
+				summary: "run-scoped leases, --wait and --no-wait, device lock and unlock, which phone an id-less --device picks",
+				body: () => `THE DEVICE LEASE ON A \`--device\` RUN
+  A physical device is shared, so a \`--device\` run takes a lease on it. The
+  lease step sits AFTER the build (a build touches no device) and before the
+  install, and the run releases what it took when the command exits: on
+  success, on a failure, on an exception, and on a Ctrl-C or a SIGTERM, which
+  it catches to give the device back before exiting 130/143. Only SIGKILL
+  escapes that, and then the lease expires on its own. Before each device step
+  -- install, launch, the log collector, verification -- the run raises the
+  expiry to now plus the larger of 60 seconds and that step's own upper bound,
+  because a child process is synchronous and no timer can tick during an
+  install. A run killed with SIGKILL therefore leaves the device leased for at
+  most the current step's bound, never less than 60 seconds.
+
+  If nobody holds the device, the run takes a lease of its own and gives it
+  back at exit. If another workspace holds it, the run WAITS: \`--wait
+  <seconds>\` (default 60) polls every 2 seconds, prints a waiting line to
+  stderr at once and then every 30 seconds with the holder, the device and the
+  holder's expiry, and refuses with STIM_DEVICE_BUSY when it runs out. It
+  keeps waiting past the holder's own expiry, because the holder can release
+  early. \`--wait 0\` refuses at once. \`--no-wait\` changes only that case: the
+  run proceeds with NO lease and prints one warning naming the holder and its
+  expiry, plus what the install costs: the same app id means it TERMINATES the
+  holder's running app, a different one means the launch only backgrounds it,
+  and when Stim cannot read the holder's app id it says so rather than
+  guessing. A free device is leased as usual under \`--no-wait\`. The two flags
+  together are STIM_BAD_ARG, and so is either one without \`--device\`, because
+  an owned simulator or emulator has no contention.
+
+  A successful \`--device\` run reports \`lease: { kind, expiresAt }\` in its
+  \`--json\`; a run that proceeded without one, or lost one after the install,
+  reports \`lease: null\`. \`stim status\` lists every lease file on the
+  machine, and \`stop\` releases the ones this workspace holds.
+
+HOLDING A DEVICE ACROSS RUNS
+  A run-scoped lease dies with the command, which is not enough for a
+  device-tool session: the next workspace's \`ios --device\` would install over
+  the app you are driving. \`stim device lock\` grants a DECLARED lease that
+  outlives the run:
+
+    stim device lock ios --for 10m     # or: android; add a UDID/serial to name one
+    stim ios --device                  # builds, installs, launches; raises the lease
+    ... device-tool work on the phone ...
+    stim device unlock                 # give it back; or let it expire
+
+  \`--for\` takes a whole number of seconds or minutes, 10s to 30m, and
+  defaults to 5m; anything else is STIM_BAD_ARG. \`--wait <seconds>\`
+  (default 60, \`0\` refuses at once) is the same wait a run does. Both
+  commands need a project and refuse outside one with STIM_NO_PROJECT, and
+  \`lock\` runs the same resolver \`--device\` does, so an unpaired phone or
+  one with Developer Mode off is refused with that resolver's own remedy
+  before any lease is written.
+
+  Locking a device this workspace already holds SETS the expiry to now plus
+  \`--for\`, which can shorten it. Locking a different device of the same
+  platform releases the first one: a workspace holds at most one lease per
+  platform. Nothing else moves an expiry -- not the app running afterwards, not
+  device-tool work, not \`status\`. Only \`lock\` and a run's own steps do.
+
+  \`stim device unlock\` releases every lease this workspace holds, or only
+  the platform named. Releasing nothing is not an error: it says so on stderr,
+  and \`--json\` prints an empty list. It releases by holder, so it still
+  works when the workspace directory was recreated and the token is gone.
+
+  With no id, \`lock\` and a \`--device\` run pick from the POOL of connected
+  devices, so two phones on one machine no longer refuse.
+
+THE POOL: WHICH DEVICE AN ID-LESS \`--device\` PICKS
+  Candidates are the connected devices the resolver already accepts: on iOS,
+  wired, paired, with Developer Mode on; on Android, every serial adb reports
+  in the \`device\` state that is not an emulator, TCP serials included. Then,
+  in order:
+
+    1. the device this workspace already leases, when it is among them;
+    2. otherwise the first one not leased -- or leased and EXPIRED -- in
+       case-folded id order.
+
+  Ids are sorted on, never names: adb has no name without one \`getprop\` per
+  serial, and models repeat.
+
+  A device this workspace leases that is NOT connected refuses with
+  STIM_NO_DEVICE naming it, rather than quietly moving to another phone. Naming
+  a different one with \`--device <id>\` refuses the same way, because a
+  workspace holds at most one lease per platform: \`stim device unlock\` first.
+
+  Candidates with none free is the wait: under \`--wait <seconds>\` the poll
+  re-LISTS devices, so a phone plugged in mid-wait is picked up as well as one
+  released mid-wait. When the wait runs out, STIM_DEVICE_BUSY names every
+  holder and its expiry. No candidate at all is the existing STIM_NO_DEVICE,
+  with the resolver's own message. \`--no-wait\` takes the first candidate
+  anyway and proceeds with no lease, as it does for one named device.
+
+  The chosen device is on the phase line and in \`--json\` (\`udid\` or
+  \`serial\`, plus \`deviceName\`), so an agent can hand the same id to its
+  device tool.`
+			},
+			release: {
+				summary: "Release configurations and ...Release variants: Metro skipped, process-proven launch, the JS swap",
+				body: () => `  A VARIANT WHOSE NAME ENDS IN "Release" IS A RELEASE BUILD (\`release\`,
+  \`productionRelease\`), and that is the whole opt-in -- there is no second
+  flag. It is the Android half of \`ios --configuration Release\` and behaves
+  the same way: AGP's bundle task embeds the JS, so Metro is skipped ENTIRELY
+  (no gate, no \`adb reverse\`, no debug_http_host, no dev-client deep link --
+  a plain \`am start\` of the launcher activity), the payload says
+  \`metroPort: null\`, and \`launched\` is proven by the app PROCESS being
+  alive on the device rather than by a bundle fetch. Device logs are still
+  collected, so \`logs --errors\` answers "does it repro in release/Hermes
+  bytecode".
+
+  On a release CACHE HIT the cached APK carries its BUILDER's baked-in JS, so
+  it is never installed as-is. Stim copies it aside, regenerates this
+  workspace's bundle with the project's own tools (\`expo export:embed\` /
+  \`react-native bundle\`, then the project's own hermesc when
+  \`hermesEnabled\` is not false in android/gradle.properties), re-packs it
+  into the copy with plain zip surgery (stored, not deflated -- the runtime
+  mmaps it), then zipaligns and re-signs with apksigner. The keystore defaults
+  to android/app/debug.keystore with the standard password; android.keystore /
+  android.keystorePassword override it (see \`guide settings\`). The cache
+  entry itself is never modified.
+
+  Before re-packing, THE ASSET GATE compares CONTENT HASHES of the assets
+  React Native emits: what this workspace just emitted under --assets-dest
+  against a manifest of what the cached build emitted, recorded as
+  assets-manifest.json inside the cache entry at build time. Same producer on
+  both sides, so the comparison is exact -- an added, a removed OR A REPLACED
+  asset (a different image under an unchanged filename) all mean NO SWAP, and
+  the run falls back to a full gradle build with a note naming an example. An
+  Android drawable is not just a file in the zip -- it has a row in
+  resources.arsc only AAPT can write -- so an APK cannot be made to carry an
+  asset it was not built with, and Stim will not install one whose JS
+  references an asset it lacks. The APK's own res/ table is never read: a
+  release build shortens every resource path (AGP's
+  optimizeReleaseResources), so those entries are \`res/-B.png\`, not the names
+  anything emitted.
+
+  AN ENTRY WITH NO MANIFEST NEVER SWAPS. One stored before asset tracking, or
+  downloaded from an Expo build-cache provider, has nothing to compare
+  against, so the run says so and builds fresh -- and that build REPLACES the
+  entry, manifest included, so the next run on the same fingerprint swaps
+  normally. The same replacement happens after any gate refusal or swap
+  failure, which is what stops a bad entry from refusing every run forever.
+
+  Local re-signing also
+  means an APK signed by CI cannot be updated over: on
+  INSTALL_FAILED_UPDATE_INCOMPATIBLE (or a version downgrade) a release run
+  uninstalls the package once and retries, printing a note -- the app's data
+  goes with it, which is why only release runs do this.
+
+  Local installs only, onto an owned emulator or, with
+  \`android --device\`, a connected physical device. Store signing and
+  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
+  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\` --
+  \`launched\` is verified by the app PROCESS staying alive, not by a bundle
+  fetch. The build cache keys on the configuration
+  (\`<fingerprint>-release-sim\`), and because a cached Release .app carries
+  its builder's baked-in JS, a cache hit regenerates THIS workspace's bundle
+  (the project's own \`expo export:embed\` / \`react-native bundle\`, plus
+  its own hermesc when Hermes is enabled) into a copy of the artifact,
+  re-signs it and installs that; any swap failure falls back to a full build
+  rather than ever installing stale JS. Device logs are still collected, so
+  \`logs --errors\` answers "does it repro in release/Hermes bytecode".
+  A run with no \`--device\` installs on the simulator only. \`ios --device\`
+  builds the \`iphoneos\` slice for a cabled iPhone and keys its cache
+  \`-device\` instead of \`-sim\`, but does not install it yet. Archives,
+  \`.ipa\` export, store signing and distribution stay out of scope.`
+			},
+			simslim: {
+				summary: "installing SimSlim and what ios.simslimProfile does to an owned simulator",
+				body: () => `OPTIONAL SIMSLIM PROFILE
+  Install SimSlim once on each Mac:
+
+    brew install mobai-app/tap/simslim
+
+  Then commit a profile and select it in .stim.json:
+
+    { "ios": { "simslimProfile": ".simslim/dev.json" } }
+
+  SimSlim requires an iOS 18 or newer simulator. On each local \`stim ios\`,
+  Stim reconciles that profile on the owned simulator before the app build.
+  The first change can update services and reboot the simulator. A matching
+  profile is a fast no-op on later launches. The settings persist across normal
+  shutdowns and reboots. Removing the setting restores stock services when
+  Stim applied the profile. Stim never changes an unowned or remote simulator.`
+			}
+		}
+	},
+	cleanup: {
+		summary: "Where simulators come from, and how they get reclaimed",
+		preamble: () => `CLEANUP AND DISK
+
+WHAT RECLAIMS AN OWNED DEVICE
+  stim worktree remove    parks eligible owned simulators and emulators
+                            (\`guide lifecycle pool\`); deletes them when
+                            parking is disabled or their setup cannot be verified
+  stim gc --delete        sweeps stim-* devices no project references, and
+                            clears verified parked simulators and emulators
+  stim gc --delete --older-than <days>
+                            also reaps the device of a project nothing has
+                            touched in that long, even though the project is
+                            still on disk
+
+Those are the only two commands that delete. \`stim stop\` shuts a device
+DOWN and leaves it assigned, which is what makes returning to a branch cost a
+boot rather than a create, a provision and a reinstall.
+
+Neither touches $STIM_HOME/stats.json: \`gc\` never reports or trims the run
+counters \`stats\` prints, and there is no reset flag. Delete that one file to
+start the counters over. A file this version cannot read -- unparseable, or
+written by a newer Stim -- costs one dim line on stderr and is otherwise left
+alone; only the next \`ios\` or \`android\` run moves an unparseable one aside
+to stats.json.corrupt-<unix ms> and starts a new one.`,
+		sections: {
+			gc: {
+				summary: "what gc and worktree remove delete, keep and refuse: orphans, stale records, locks, leases, EAS sessions",
+				body: () => `LINKED WORKTREES
+  \`stim worktree remove\` works with any linked worktree, warmed or not.
+  Git registration identifies the worktree; a Stim registry entry is not
+  required. The command reclaims any owned resources it finds, checks for
+  uncommitted and unpushed work, and removes the linked checkout. Git-created
+  branches stay. A branch with an existing Stim ownership record is deleted
+  only when it has no unique commits.
+
+ON THE SOURCE CHECKOUT
+  git cannot remove a repository's main working tree, and deleting the source
+  checkout is not what anyone meant -- so there, and only there,
+  \`worktree remove\` reclaims the ENVIRONMENT and nothing else: the owned
+  devices are parked or deleted, the Metro port freed, the registry entries
+  (including nested monorepo app dirs) dropped, and the global workspace
+  directory deleted. The tree itself is never touched, which is also why the
+  dirty-tree and unpushed guards do not apply on that path.
+  It ends with:
+    Reclaimed the environment; the working tree stays (it is the source checkout).
+  A registered project directory that is not a git repo at all gets the same
+  environment reclaim -- there is nothing else remove could mean there.
+
+The delete paths and \`stop\` do not check simulator occupancy. An explicit
+\`stim stop\` shuts down this workspace's Stim-owned simulator, including a
+simulator used by a UI-test runner. It never shuts down an unowned simulator.
+
+If a delete fails, the device's config record is KEPT and the command reports
+it. A record is what makes the device findable again, so it outlives a failed
+teardown rather than turning it into an orphan.
+
+BUILD LOCKS
+  \`gc\` also reports the single-flight build locks (above): the ones whose
+  builder is no longer running are debris a reboot or a kill left behind, and
+  \`gc --delete\` clears them. A lock whose builder IS running is a build in
+  progress -- it is named in the report and touched by nothing, because
+  removing it would put a second workspace on the same compile.
+
+DEVICE LEASES
+  A workspace can hold a timed lease on a physical device. The lease is one
+  file under ~/.stim/device-locks, and it expires on its own. \`gc\` reports
+  the lease files whose expiry has passed; \`gc --delete\` removes those
+  files, re-reading each one under its own lock first, so a lease renewed in
+  the meantime survives. Two kinds are reported and KEPT: a file that does
+  not parse, which no run may take the device around, and an unexpired lease
+  whose holder directory is gone. \`stim status\` lists every lease file with
+  its holder and expiry, including holders no config knows. \`stop\` and
+  \`worktree remove\` release the leases of the workspace they act on, and
+  nothing else deletes a lease file: never remove another workspace's.
+
+A device leaks when a project is abandoned WITHOUT either delete path -- the
+sim survives with nothing pointing at it. \`stim gc\` (no flag, writes
+nothing, always safe) reports those; \`gc --delete\` reaps them, and in the same
+run drops the dead config ENTRIES those projects left behind and frees their
+Metro ports.
+
+REMOTE EAS SESSIONS
+  Plain \`stim gc\` is a dry run. \`gc --delete\` can stop active stim-* EAS
+  sessions after workspace state is missing. The stop needs verified
+  project, name, platform, and status ownership. The same run also cleans the
+  local state that it can prove is stale.
+
+  A fixed ownership record and lock live under ~/.stim/machine/eas,
+  independent of STIM_HOME. Unclaimed sessions are never stopped.
+  Missing config.json does not authorize cleanup.
+  The exact recorded workspace state path must prove that the session ID is
+  absent.
+  If claim removal fails after a verified stop, the session is stopped, but the
+  workspace record is kept for reconciliation.
+
+  If a registered root is missing or unreadable, the EAS sweep fails closed and
+  leaves the remote EAS session running. Independent local cleanup continues
+  for entries it proves stale.
+
+THE MIRROR IMAGE: A STALE DEVICE RECORD
+  A device deleted out from under a LIVE project (by hand, or by Xcode) leaves
+  the opposite problem: the record points at a sim that is not on the machine,
+  and \`stim status\` warns about it on every run. \`gc\` reports these under
+  "Stale device records", and \`gc --delete\` clears the RECORD -- only the
+  record. There is no device left to shut down or delete, so nothing is issued
+  at simctl or avdmanager, and the project keeps its entry, its label and its
+  Metro port. The next \`ios\` / \`android\` creates a fresh owned device.
+
+THE ONE CASE GC WILL NOT REAP
+  If the config is gone entirely (deleted ~/.stim, or a throwaway
+  STIM_HOME), gc cannot tell your stale devices from another config's LIVE
+  ones, so it refuses to delete anything. It still NAMES the stim-* devices
+  it found, so you can judge. Delete them yourself:
+    xcrun simctl delete <udid>
+    avdmanager delete avd -n <name>`
+			},
+			collector: {
+				summary: "log collector reaping: an unproven collector pid, and why the app on a phone closed",
+				body: () => `WHAT ELSE STOP REAPS
+  The device-log collectors (\`simctl log stream\` / \`adb logcat\`) that
+  \`ios\` / \`android\` attach after launch. They are recorded in
+  the global workspace state.json, and nothing outside this workspace can name them,
+  so \`stop\` is what stands between a teardown and a log stream that outlives
+  the device it was reading. A fresh \`ios\` / \`android\` run also kills the
+  previous collector for that platform before starting its own.
+
+  A PHYSICAL IPHONE'S COLLECTOR IS THE SAME PROCESS with one difference: on
+  hardware the collector IS the launch. \`devicectl\` connects an app's
+  streams only when it is the process that starts the app, so the collector
+  runs \`devicectl device process launch --console\` itself rather than
+  attaching after the fact. It registers under the same \`ios\` key, carries
+  the same --root in its title, is proven and replaced by the same pid rules,
+  and is reaped by the same \`stop\`.
+
+  THE APP'S LIFETIME IS BOUND TO THAT COLLECTOR, and this is the one place a
+  phone behaves worse than a simulator. \`devicectl device process launch
+  --console\` keeps the app attached to the launching process, so anything that
+  ends the collector ends the APP ON THE PHONE: \`stop\`, \`gc --delete\`,
+  \`worktree remove\`, a fresh \`ios --device\` run stopping its predecessor,
+  a crash, the host sleeping, or the cable coming out. Measured: SIGTERM to the
+  collector alone terminates the app. The phone has no owned-device registry
+  entry. \`stop\` closes the app and releases this workspace's leases.
+  Nothing is uninstalled, and the next \`ios --device\` starts it again.
+
+  Unplugging the phone ends devicectl, which ends the collector: it unregisters
+  itself and exits either way. A separately held \`device lock\` lease survives
+  collector exit until released or expired; \`gc --delete\` can remove its
+  expired lease file.
+  WHICH record it writes on the way out depends on devicectl's exit code, and
+  that code is unverified until someone pulls a cable: a zero exit is
+  collector_stopped, a non-zero one is collector_failed, because on hardware
+  a non-zero devicectl exit is the only evidence a launch or console failed.
+  See \`guide logs\` for what it can and cannot carry.
+
+  Before signalling a recorded collector pid, \`stop\`, \`gc --delete\`,
+  \`worktree remove\`, and a fresh \`ios\` / \`android\` run each read that
+  persisted process identity and require it to match the exact process
+  registered for this workspace and platform. A pid that cannot be proven is
+  reported and left alone: the
+  kernel reuses pids, and an unreaped record is a smaller problem than a
+  signal delivered to someone else's process. A fresh \`ios\` / \`android\`
+  run starts its replacement anyway, leaving the unproven pid to clear on its
+  own. A collector started by an older Stim has no process identity token, so
+  it reports as unverified until its record clears -- which happens when its
+  own device's log stream ends and it unregisters itself, or when the next
+  \`ios\` / \`android\` run overwrites the record with its own, whichever
+  comes first; the old process itself keeps running until it exits on its own.
+
+  A different exact OS start identity proves PID reuse: the recorded collector
+  is gone, and the unrelated process is never signalled. A missing, malformed,
+  or unreadable identity leaves the record unverified and kept for a retry.
+  Wall-clock timestamps and command names are not ownership proof.`
+			},
+			disk: {
+				summary: "disk usage, AVD and build-log sizes, the data partition, trimming the shared caches",
+				body: () => `DISK
+  Logs, state, pidfiles and Xcode DerivedData are under the global workspace
+  directory, and \`worktree remove\` reclaims them. Gradle retains its normal
+  project build directories while sharing task outputs through its build cache.
+
+  Android AVDs normally live under ~/.android/avd, and a booted owned AVD can
+  use several GB. \`worktree remove\` deletes the workspace's owned AVD; plain
+  \`stop\` only shuts it down for reuse. Stim uses Android's default Quick Boot
+  unless displayless Linux requires software rendering, where snapshots are
+  disabled. The first boot and a boot after the emulator, system image, or AVD
+  settings change are cold, while later supported boots load the one automatic
+  snapshot saved on exit. \`stop\` waits for the emulator process and, when
+  enabled, the snapshot save to finish.
+  New owned AVDs default to an 8 GiB data partition, though project settings can
+  change it. When enabled, Quick Boot keeps one automatic snapshot, and \`worktree remove\`
+  deletes the whole AVD.
+  \`gc\` prints the on-disk size beside an orphaned or stale owned Android AVD
+  when its content directory can be read.
+
+  So are the logs, and one of them is not small: build-ios.ndjson /
+  build-android.ndjson hold the whole xcodebuild or gradle transcript at debug
+  level, which for a cold build is tens of megabytes (74 MB measured on one
+  first iOS build of a real app). They are worth that -- a build that fails at
+  minute nine is unreadable any other way -- and they are per workspace, not
+  global, so \`worktree remove\` reclaims them along with everything else in
+  the global workspace directory. Each build starts its transcript file over, so the log
+  holds one run and a workspace you keep building in does not accumulate them.
+
+  Simulators are large and live in the CoreSimulator device set, not in your
+  project. If the disk is filling up, Stim's own devices are usually not the
+  bulk of it -- Apple's default simulators and old runtimes are. Useful:
+    xcrun simctl delete unavailable     # sims for runtimes you removed
+    xcrun simctl list devices           # see everything
+    stim gc                           # report dead entries, orphans, caches
+  Xcode recreates default simulators on demand, so deleting them is safe.
+
+New owned Android AVDs use an 8 GiB data partition by default. This leaves room
+for repeated app installs while capping userdata growth below the 10 GiB
+setting measured on the selected API 36 profile. Set
+\`android.dataPartitionSizeGb\` to a whole number from 6 through 16384 when a
+project needs another size. Android userdata grows but does not shrink, so the
+setting applies only to a newly created AVD; recreate the environment to adopt
+a changed value.
+
+SHARED BUILD CACHES
+  The caches that make a second workspace fast are alive by design and never
+  included in a plain \`gc --delete\`. Every \`gc\` run reports them anyway,
+  each row tagged (registered) or (detected), with its size:
+    stim gc                            # report, caches included
+    stim gc --delete --older-than 30   # trim entries nothing has used
+    stim gc --delete --cache all       # empty them whole, index-backed ones
+                                         # (the Xcode CAS) included
+  $STIM_HOME/ccache (default ~/.stim/ccache) holds the Android C++ objects
+  \`stim android\` compiles through ccache. ccache keeps it under CCACHE_MAXSIZE
+  on its own, so \`gc\` reports its size and leaves it alone; --older-than
+  skips it, and \`--cache all\` empties it whole like the Xcode CAS. That
+  bound is Stim's: it sets CCACHE_MAXSIZE on the Gradle run, which wins over
+  a max_size written into the cache directory's own ccache.conf.
+
+  The Gradle build cache under GRADLE_USER_HOME (default ~/.gradle) is
+  report-only because every Gradle build shares it. Stim reports its size
+  but never prunes or empties it, including with --older-than or --cache all.
+  Trim rather than empty. Emptying costs the next build in every project the
+  time the cache was saving.`
+			}
+		}
+	},
+	settings: {
+		summary: "Settings Stim reads, and where they can live",
+		body: () => `SETTINGS
+
+There is no \`stim config\` command. Settings are JSON files, edited by
+hand or committed; command-line selectors override their matching settings.
+
+Resolution order, first match wins:
+  1. project layer   ~/.stim/config.json, under this project's entry
+  2. repo layer      ~/.stim/config.json, under this repo's git common dir
+  3. committed       .stim.json beside the app's package.json
+  4. machine defaults  ~/.stim/config.json, top-level optimizations only
+  5. Stim default
+
+The committed file is plain JSON and travels with the app. Each monorepo app
+reads its own file, never an ancestor's runtime settings. A single-app repository
+still uses its root file. Existing machine project/repository overrides keep
+their precedence. Move root runtime settings into each relevant app when
+upgrading; relative profile/config/provider paths resolve from the app directory.
+
+Worktree copying is repository-wide: worktree warm reads worktree.exclude and
+worktree.defaultBranch from the source checkout's root .stim.json, not from
+individual apps. Keep those rules at the repository root; runtime files and
+worktree-copy policy are separate scopes.
+
+An app's .stim.json can contain:
+
+  {
+    "ios": {
+      "deviceType": "iPhone 17 Pro",
+      "runtime": "26.2",
+      "simslimProfile": ".simslim/dev.json"
+    },
+    "android": { "variant": "productionDebug" },
+    "caches": ["~/.myapp-metro-cache"]
+  }
+
+KEYS STIM READS
+  ios.deviceType        e.g. "iPhone 17 Pro" -- the simulator model this
+                        workspace's owned sim is created as, spelled exactly as
+                        \`xcrun simctl list devicetypes\` names it, and one an
+                        installed runtime can create. The \`--device-type\`
+                        flag overrides this per invocation. A name no installed
+                        runtime offers is STIM_BAD_ARG and the creatable names
+                        are printed
+  ios.runtime           e.g. "26.2" -- the iOS runtime that sim is created on,
+                        as a version ("26.2") or a runtime's full name
+                        ("iOS 26.2"); nothing else matches. The \`--runtime\`
+                        flag overrides this per invocation, and an uninstalled
+                        version refuses the same way
+  ios.configuration     e.g. "Release" -- the Xcode configuration to build
+                        (simulator only). Committing
+                        { "ios": { "configuration": "Release" } } makes every
+                        \`stim ios\` in the app a release-shaped build:
+                        embedded JS, no Metro, cache keyed -release-sim, and
+                        a JS-bundle swap on cache hits. The \`--configuration\`
+                        flag overrides this per invocation. Unset means Debug.
+  ios.remote            "proxy" or "eas" to use that remote backend, the same
+                        as passing \`--remote proxy\` or \`--remote eas\`. The
+                        build still runs here; only the device is elsewhere.
+  ios.simslimProfile    a SimSlim JSON profile under the app directory,
+                        at most 64 KiB. Install the
+                        external tool once with
+                        \`brew install mobai-app/tap/simslim\`. SimSlim requires
+                        an iOS 18 or newer simulator. Each local \`stim ios\`
+                        reconciles the profile on its Stim-owned simulator.
+                        The first change can reboot it; a matching profile is a
+                        fast no-op. Removing the setting restores stock services
+                        when Stim applied the profile. Absolute paths, root or
+                        symlink escapes, and missing files are refused before
+                        simulator creation. Remote and unowned simulators are
+                        never changed.
+  ios.signingIdentity   e.g. "Apple Development: Jane (TEAMID5678)" -- the
+                        keychain identity to re-seal a \`--device\` build with,
+                        overriding the one Stim derives from the artifact's own
+                        embedded.mobileprovision. Discovery is zero-config, so
+                        this exists only for the case discovery cannot cover.
+                        The name must be one \`security find-identity -v -p
+                        codesigning\` prints.
+  ios.signingIdentitySha1
+                        the 40-character hex SHA-1 hash printed beside that
+                        name. Set it when two certificates share one common
+                        name: Stim is non-interactive, so it refuses an
+                        ambiguous identity rather than picking one. It wins
+                        over ios.signingIdentity.
+  ios.lanHost           e.g. "192.168.1.42" -- the address a phone uses to
+                        reach this workspace's Metro on an \`ios --device\`
+                        Debug run, pinning the interface on a multi-NIC Mac
+                        whose en0 is not the one the phone shares. A bare
+                        address or hostname ONLY: never a scheme, a port, or a
+                        URL, because the channels that carry it to the phone
+                        (the dev-client deep link and the bundle's ip.txt)
+                        compose the URL themselves. Unset means Stim orders the
+                        host's non-internal IPv4 interfaces en0 first, then the
+                        remaining en* by index -- react-native-xcode.sh's own
+                        heuristic, so Stim and a plain Xcode run pick the same
+                        interface.
+  android.systemImage   e.g. "system-images;android-36;google_apis;arm64-v8a"
+                        -- the sdkmanager package id the owned AVD is created
+                        from. The \`--system-image\` flag overrides this per
+                        invocation, and an id this SDK has not installed is
+                        STIM_BAD_ARG with the installed ids printed
+  android.dataPartitionSizeGb
+                        whole GiB for a newly created owned AVD's data
+                        partition. Defaults to 8; accepts 6 through 16384.
+                        Existing AVDs are never resized because Android
+                        userdata grows but does not shrink. Recreate the
+                        environment to adopt a changed value.
+  android.avdConfigFile
+                        path under the app directory to a flat native
+                        key=value INI fragment,
+                        at most 64 KiB. Stim parses it and
+                        merges supported values into avdmanager's generated
+                        config.ini before first boot; it is never used as a
+                        replacement file. Absolute paths, app-directory or
+                        symlink escapes, malformed or duplicate lines, and
+                        unsupported keys are refused before AVD creation.
+  android.avdConfig     flat object of the same native keys. It merges key by
+                        key across settings layers and overrides the selected
+                        avdConfigFile fragment. Boolean values accept true,
+                        false, "yes", or "no"; numbers and enums are checked.
+                        Supported keys and values:
+${ANDROID_AVD_CONFIG_HELP.map((line) => `                          ${line}`).join("\n")}
+                        Identity, architecture, host path, storage, image,
+                        kernel, camera, snapshot, boot-lifecycle, and unknown
+                        keys are protected. The emulator may normalize a valid
+                        value. These overrides apply only to a newly created
+                        AVD; existing and recovered AVDs are never rewritten.
+                        On displayless Linux, Stim launches with
+                        -gpu swiftshader_indirect -noaudio; those arguments
+                        override hw.gpu.enabled, hw.gpu.mode, hw.audioInput,
+                        and hw.audioOutput for that headless launch.
+  android.variant       e.g. "productionDebug" -- the gradle variant to
+                        assemble and install on a project with product
+                        flavors. A repo like tlon-mobile with
+                        flavorDimensions "profile" and production/preview
+                        flavors has NO plain assembleDebug output: commit
+                        { "android": { "variant": "productionDebug" } } and
+                        \`stim android\` runs assembleProductionDebug,
+                        finds the APK in apk/production/debug/ and keys the
+                        build cache on the variant. The \`--variant\` flag
+                        overrides this per invocation. Unset means plain
+                        assembleDebug. A variant whose name ENDS IN Release
+                        (\`release\`, \`productionRelease\`) is a release
+                        build: embedded JS, no Metro, cache keyed on the
+                        variant, and an APK re-pack on cache hits. See
+                        \`guide lifecycle release\`.
+  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.
+  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".
+  android.remote        "proxy" or "eas"; the Android half of ios.remote
+  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)
+                        first tries an authenticated and working ngrok.
+                        After an auth refusal,
+                        or any failure before ngrok returns a URL, it falls back
+                        to cloudflared. "off" asserts the device
+                        shares this machine and is the only mode that needs no
+                        tunnel. "expo" lets the Expo dev server tunnel itself.
+                        "cloudflared" and "ngrok" name a managed provider
+                        explicitly. Any other value is refused as invalid.
+  metro.ngrokUrl        the stable managed ngrok URL. It requires metro.tunnel
+                        "ngrok" and passes --url to ngrok http. Stim owns
+                        this process.
+  metro.publicUrl       an existing tunnel's URL. Takes precedence over
+                        starting one, whatever metro.tunnel says -- Stim
+                        did not create it, so a Metro request through it is
+                        still gated the same way a managed tunnel's is. Set it
+                        before Expo start so the manifest advertises it.
+  worktree.exclude      ignored-path skip list for worktree warm. Settings
+                        come from the source checkout's repository-root
+                        .stim.json. A nonempty .worktreeexclude in the source
+                        checkout replaces this setting. Registered nested Git
+                        worktrees are always skipped.
+  worktree.defaultBranch
+                        the branch the source checkout is expected to sit on,
+                        read only by \`worktree warm --refresh\`, which WARNS
+                        (and continues) when the source checkout is on another
+                        branch, because the copy then carries that branch's
+                        dependencies. Unset, the branch
+                        \`git symbolic-ref --short refs/remotes/origin/HEAD\`
+                        names is used; set it when origin/HEAD is missing or
+                        wrong. Neither answering means no warning, not an error.
+  cache.provider        one optional SECOND-TIER cache provider: a module
+                        path relative to the settings file that names it, or a
+                        package name. It implements the @stim-cli/cache
+                        contract and can serve Metro transforms, native build
+                        artifacts, or both. The local filesystem stays tier
+                        one; a provider is read only after a local miss and
+                        written after the local write. Failures and timeouts
+                        are cache misses, never build or bundle failures.
+                        Stim ships no provider and never configures one.
+                        This module is EXECUTABLE CODE that every worktree of
+                        this app runs; review a committed value the way
+                        you review a build script.
+                        \`stim ios\` and \`stim android\` use it unless
+                        artifact or remote artifact caching is disabled. Metro
+                        uses it only when the project's own metro.config.js
+                        calls \`sharedCacheStores()\` from @stim-cli/metro: the
+                        store Stim injects for you (bare in-process, or the
+                        Expo config override) stays local-only.
+  cache.options         free-form object handed to that module's factory. It
+                        merges key by key across settings layers. Keep secrets
+                        out of the committed file: read them from the
+                        environment or the machine layers.
+  caches                extra shared-cache paths for \`gc\` to report. A JSON
+                        array; every path is treated as a flat store.
+
+Each setting takes its documented type: string, array of strings, number,
+boolean, or object. A value of the wrong type is
+refused by name on every command that resolves settings, so a wrong shape never
+falls back to a default silently. \`stim doctor\` reports it as a finding
+instead of refusing. The exception is \`optimizations.android.casToolchain\`:
+an invalid value warns and falls back to ccache, or no compiler cache when
+\`compilerCache\` is \`none\`. \`doctor\` also reports the invalid setting.
+
+Anything else is IGNORED, and Stim warns about it by name on every run that
+resolves settings. If you see such a warning, the key was either renamed or
+removed -- check this list rather than assuming it still applies.
+
+\`stim doctor\` checks the settings themselves on every run, whatever
+--platform says, because a rotted machine setting is not a native-platform
+problem. It reports, as notes naming the key, the file it came from, and the
+line that clears it: a setting whose path no longer exists, a setting that needs
+a companion the config does not supply, a key Stim no longer reads, and a
+config file that is not valid JSON. It skips the \`projects\` registry, where an
+entry for a deleted checkout is normal and \`gc\` owns the cleanup.
+
+CONCURRENCY LIMITS ARE MACHINE-LEVEL, NOT A PER-PROJECT SETTING
+The caps above are not in the layered settings -- they are not per-project,
+because the resource they share (cores, RAM, booted simulators) is the whole
+machine's. They live under a top-level \`concurrency\` key in
+~/.stim/config.json, edited by hand:
+
+  {
+    "concurrency": { "maxBuilds": 2, "maxDevices": 3 }
+  }
+
+or via the environment, which overrides the file:
+
+  STIM_MAX_BUILDS=2 STIM_MAX_DEVICES=3 stim ios
+
+Unset, 0, or any non-positive value means NO enforcement -- the default, where
+Stim limits nothing. See \`guide lifecycle concurrency\` for what each cap
+does.
+
+THE DEVICE POOL BOUNDS ARE MACHINE-LEVEL TOO
+\`pool.iosParkedMax\` caps how many parked simulators \`worktree remove\` may
+leave behind for a later workspace to adopt. It is machine-level for the same
+reason: the disk they sit on is the whole machine's, about 2.5 GB each.
+
+  {
+    "pool": { "iosParkedMax": 3 }
+  }
+
+in ~/.stim/config.json, or STIM_POOL_IOS_PARKED_MAX in the environment, which
+overrides the file. Absent means 3. \`0\` turns parking and adoption off:
+\`worktree remove\` deletes the simulator, \`ios\` never adopts, and a pool
+that already exists stays where it is until \`gc --delete\`. A value that is
+not a whole number 0 or more is refused by name on \`worktree remove\` and
+\`ios\`, and warned about by \`status\`, \`gc\` and \`doctor\`.
+
+Android uses \`pool.androidParkedMax\` or STIM_POOL_ANDROID_PARKED_MAX with
+these same defaults and validation rules. \`android\` validates that bound;
+\`worktree remove\`, \`status\`, \`gc\` and \`doctor\` check the applicable
+platform bounds. Android adoption matches the system image and AVD creation
+settings, preserves the APK, and clears app data before launch. See
+\`guide lifecycle pool\` for cleanup and the system state that remains.
+
+When STIM_HOME is set, parking and adoption are OFF unless
+the corresponding STIM_POOL_IOS_PARKED_MAX or STIM_POOL_ANDROID_PARKED_MAX
+is set too. A redirected home is a scoped config --
+test suites and the end-to-end harness use one -- and a scoped config must not
+leave simulators on the machine it cannot account for. A redirected home that
+wants a pool says so with the variable.
+
+STIM NEEDS NO PROJECT CHANGES TO RUN
+Nothing above is required to use Stim. The performance caches that used to
+be setup steps are supplied by Stim on the command lines it composes itself:
+
+  xcodebuild   COMPILATION_CACHE_ENABLE_CACHING / COMPILATION_CACHE_CAS_PATH /
+               SWIFT_ENABLE_COMPILE_CACHE / CLANG_ENABLE_PREFIX_MAPPING /
+               CLANG_OTHER_PREFIX_MAPPINGS -- so no Podfile post_install block
+               (Xcode 26+ only, and skipped when the project configured ccache,
+               which defeats it)
+  gradlew      --build-cache -- so no org.gradle.caching=true in a committed
+               gradle.properties. Debug builds add
+               -PreactNativeArchitectures=<target ABI> when the owned
+               emulator system image or physical device proves the ABI;
+               unknown targets and Release builds stay universal. The same run
+               carries the ccache launcher and CCACHE_BASEDIR /
+               CCACHE_NOHASHDIR when ccache is on PATH -- so no
+               externalNativeBuild cmake arguments in a committed
+               build.gradle.
+  start        a shared Metro FileStore, APPENDED to whatever the project
+               configured -- so no metro.config.js. On a bare project Stim
+               hosts Metro itself and adds it to the config it loaded; on Expo
+               SDK 54+ the child loads Stim's config adapter through
+               EXPO_OVERRIDE_METRO_CONFIG. Expo SDK 53 and older run with
+               their normal Metro cache.
+
+Each of those prints one dim line saying it happened. There is no setup skill
+and no init command; \`stim doctor\` reports the project-side settings as
+things you need only if you ALSO build outside Stim.
+
+OPTIMIZATION SWITCHES
+Put an optimizations object at the TOP LEVEL of $STIM_HOME/config.json
+(default ~/.stim/config.json) to set machine defaults. Merge it into the
+existing file; preserve the project and device records. No project changes
+are required. The same object in .stim.json, or the existing repository/project
+settings layers, overrides individual values. Explicit false wins; removing a
+key inherits the next layer. Changes apply on the next build or Metro restart.
+
+  {
+    "optimizations": {
+      "buildCache": true,
+      "remoteBuildCache": true,
+      "releaseBundleSwap": true,
+      "metroSharedCache": true,
+      "ios": {
+        "compilationCache": true,
+        "swiftCompilationCache": false,
+        "prefixMapping": true
+      },
+      "android": {
+        "compilerCache": "auto",
+        "pch": "auto",
+        "gradleBuildCache": true,
+        "targetAbiOnly": true
+      }
+    }
+  }
+
+The example shows the defaults. Full setting names and behavior:
+  optimizations.buildCache
+    false skips native artifact reads AND writes, including remote providers.
+    Compiler caches remain independent. The existing --no-build-cache flag
+    only bypasses reads and still stores the fresh build.
+  optimizations.remoteBuildCache
+    false skips both optional remote artifact providers, including loading
+    their modules and authentication. Local artifact caching stays enabled.
+    Stim ships no network provider or hosted cache. Remote artifact reuse
+    requires a provider configured through cache.provider or Expo.
+  optimizations.releaseBundleSwap
+    false always builds Release from source, including the current JS;
+    it never installs an old embedded bundle. Fresh artifacts can still store.
+  optimizations.metroSharedCache
+    false stops Stim appending its shared Metro store on both dev servers.
+    Project-configured stores remain the project's choice. Replace the removed
+    machine setting caches.injectMetroStore=false with this setting set false.
+  optimizations.ios.compilationCache
+    controls Xcode compilation caching (Xcode 26+).
+  optimizations.ios.swiftCompilationCache
+    opts into experimental Swift caching, requiring compilationCache=true.
+  optimizations.ios.prefixMapping
+    controls Clang source/DerivedData prefix mapping. false clears Stim's
+    mappings. The existing Xcode version and project-ccache guards still apply.
+  optimizations.android.compilerCache
+    auto uses a CAS manifest if supplied, otherwise the normal ccache setup.
+    ccache explicitly selects that setup; none stops Stim injecting it and
+    disables inherited ccache. Project-defined compiler integrations can still
+    override CMake settings. cas asks for the manifest below; with no usable
+    manifest the build warns once and uses ccache rather than refusing. A value
+    outside auto|ccache|cas|none is still refused by name.
+  optimizations.android.casToolchain
+    absolute path to the experimental Apple Clang toolchain JSON manifest.
+    STIM_ANDROID_CAS_TOOLCHAIN overrides this path. An explicit ccache or none
+    selection overrides automatic CAS selection even with that environment
+    variable set. Any value that is not an absolute path, whatever its type,
+    and a manifest that is missing, unreadable, or does not name an executable
+    clang, clangxx, lld, ar and ranlib plus an existing resourceDir, degrade to
+    the compiler cache the selection leaves -- ccache, or none when
+    compilerCache is none -- in one warning naming this key and the file it came
+    from. \`stim doctor\` resolves the same manifest and reports what the build
+    would warn about as a note: a path that is not there, from this key or from
+    that environment variable, or a manifest that is there and cannot be used.
+    For prerequisites, see:
+    https://stim.appandflow.com/docs/android-cas
+  optimizations.android.pch
+    auto keeps library/project policy, with PCH off by default when Stim supplies
+    ccache. on/off overrides Gradle CMAKE_DISABLE_PRECOMPILE_HEADERS arguments;
+    CMake target-level overrides still win. on does not fix stock ccache's
+    cross-worktree PCH limitations.
+  optimizations.android.gradleBuildCache
+    false passes --no-build-cache to Gradle, overriding org.gradle.caching=true.
+  optimizations.android.targetAbiOnly
+    false stops narrowing Debug builds to the device ABI. Release is always
+    universal; project ABI filters still apply.
+
+Android CAS, explicit PCH modes, and changed iOS compiler options use separate
+native artifact keys. Android ccache and none share an artifact key when their
+PCH mode matches; disable artifact caching too to force native compilation. Legacy Expo providers
+cannot key these compiler profiles, so Stim skips that tier for custom profiles
+and Android CAS. Providers implementing the Stim key contract remain usable.
+Android compiler/PCH profiles also get separate CMake staging directories under
+<module>/.cxx/stim-<profile>, or under the project's custom staging root. Switching
+backends in Stim selects the matching directory without deleting previous builds.
+These directories accumulate across profile changes and shim upgrades. Stim
+does not prune them; remove an obsolete generated profile only with all native
+builds stopped. Worktree removal reclaims profiles with the rest of the tree.
+Direct Gradle runs keep their own configuration. These switches control Stim's
+build invocations; they do not edit Xcode, Gradle, CMake, or Metro project files.
+
+Reading the timeline for it: on Expo, \`cache_store_requested\` is Stim saying
+it asked (it set EXPO_OVERRIDE_METRO_CONFIG on a process it does not run, which
+is all this side can know), and \`cache_store_added\` is the adapter reporting
+from inside that process that the store is in the config Metro loaded. Only the
+second one means transforms are being shared. A bare project writes
+\`cache_store_added\` directly, because there Stim adds the store itself.
+
+TEMPORARY STORAGE
+Large temporary copies for iOS app preparation, release JS/APK
+swaps, and the doctor fingerprint checkout select a writable directory on the
+relevant filesystem. App/APK preparation uses the artifact volume. Worktree
+warm copies directly to the destination and does not use temporary storage.
+A system temporary directory on that
+volume is preferred, then a writable ancestor of the relevant path. Staging
+is private and outside Git working trees, so ignored secrets cannot enter
+Git status or git add. If no safe location exists, the operation refuses.
+
+Set STIM_TMPDIR or top-level tempDir in $STIM_HOME/config.json (default
+~/.stim/config.json) to override placement. STIM_TMPDIR takes precedence.
+The value must be an absolute directory outside Git working trees; missing
+directories are created privately. An override is used even on another volume.
+Doctor reports cross-volume copy costs and invalid temporary settings; it
+creates no directories for this placement check. Unset the override to restore
+automatic selection. An example machine setting:
+
+  { "tempDir": "/Volumes/SSD/stim-tmp" }
+
+Small tool-response and entitlement files still use the system temporary
+directory. Build-cache storage stages beside its destination independently of
+tempDir. Keeping build output and its cache on different volumes still requires
+a full copy. iOS build output lives under STIM_HOME/workspaces; Android APKs
+live under the project's android/app/build/outputs/apk. Doctor compares these
+locations with the cache, using resolved symlinks and filesystem device IDs.
+It checks the current layout; arbitrary provider-returned paths and future
+mount changes cannot be predicted. Same-volume placement permits cloning when
+the filesystem supports it; it does not prove cloning occurred. On macOS,
+cp -c can silently fall back to copying and exit successfully.
+
+CACHE LOCATIONS ARE MACHINE-LEVEL TOO
+The shared build cache and Metro transform cache default to living under
+~/.stim. To relocate them (say, to an external disk), set a top-level
+\`caches\` key in ~/.stim/config.json, edited by hand -- absolute paths:
+
+  {
+    "caches": { "buildCache": "/Volumes/SSD/stim/build-cache",
+                "metroCache": "/Volumes/SSD/stim/metro-cache" }
+  }
+
+STIM_BUILD_CACHE / STIM_METRO_CACHE in the environment override the file.
+The CLI and both cache packages resolve these identically, so every process
+finds the same store regardless of shell profile. A relative path is ignored.
+The Metro value is a PARENT root. The sanitized package name is appended below
+it, so apps remain separately reportable and prunable. Earlier releases used an
+overridden Metro root as one flat store. A new registration replaces that legacy
+parent entry and marks the named layout. If an older package registers it again,
+current gc ignores the exact unmarked legacy parent while a marked child exists.
+A marked store that later becomes another override parent remains visible but is
+report-only while its marked child exists. Root-level legacy files remain
+untouched for manual cleanup.
+
+PREFER SELF-REGISTRATION OVER THE 'caches' SETTING
+There is no 'cache' command. A cache registers itself from code instead, once,
+and every 'gc' report shows it from then on, tagged (registered):
+
+  import { register } from 'stim/cache-manifest';
+  register({ dir: '<dir>', name: '<what to call it>', entriesDepth: 2 });
+
+entriesDepth is how far below dir one entry sits (default 1, a flat store).
+Pass 2 for a root with a layer of grouping above the entries -- a Metro
+FileStore shards across 256 directories, a build cache is keyed
+<platform>/<key> -- or 'gc --delete --older-than N' removes a whole shard or
+platform instead of one entry. Pass prune: 'atomic' for a cache whose index
+references its own data (an LLVM CAS): it is then left alone by --older-than
+and emptied whole only by 'gc --delete --cache all'.
+Registration is idempotent and keyed on the directory.`
+	}
+};
+//#endregion
+//#region src/commands/guide.ts
+function topicNames() {
+	return Object.keys(TOPICS);
+}
+function topicByName(name) {
+	return Object.hasOwn(TOPICS, name) ? TOPICS[name] ?? null : null;
+}
+const LOOKUPS = /* @__PURE__ */ new Map();
+function sectionLookup(name) {
+	const cached = LOOKUPS.get(name);
+	if (cached) return cached;
+	const lookup = Object.create(null);
+	for (const [sectionName, section] of Object.entries(topicByName(name)?.sections ?? {})) {
+		lookup[sectionName] = section;
+		for (const alias of section.aliases ?? []) lookup[alias] = section;
+	}
+	LOOKUPS.set(name, lookup);
+	return lookup;
+}
+function sectionNames(name) {
+	return Object.keys(topicByName(name)?.sections ?? {});
+}
+const COMMAND_NOTATION = "Commands use `stim`. If it is not installed globally, replace `stim` with `npx stim`.";
+function wordCount(text) {
+	return text.trim().split(/\s+/).filter(Boolean).length;
+}
+function renderSectionIndex(name) {
+	const topic = topicByName(name);
+	if (!topic?.sections) return null;
+	const entries = Object.entries(topic.sections);
+	const width = Math.max(...entries.map(([sectionName]) => sectionName.length));
+	const lines = ["SECTIONS"];
+	for (const [sectionName, section] of entries) {
+		if (section.separator) {
+			lines.push("", section.separator, "");
+			if (section.context) lines.push(section.context, "");
+		}
+		lines.push(`  ${sectionName.padEnd(width)}  ${`${wordCount(section.body())}w`.padStart(6)}  ${section.summary}`);
+		for (const alias of section.aliases ?? []) lines.push(`    = ${alias}`);
+	}
+	lines.push("", `Read one with:  stim guide ${name} ${topic.sectionHint ?? "<section>"}`);
+	return lines.join("\n");
+}
+function renderTopic(name) {
+	const topic = topicByName(name);
+	if (!topic) return null;
+	if (topic.body) return `${COMMAND_NOTATION}\n\n${topic.body()}`;
+	return `${COMMAND_NOTATION}\n\n${topic.preamble?.() ?? ""}\n\n${renderSectionIndex(name) ?? ""}`;
+}
+function renderSection(name, section) {
+	const lookup = sectionLookup(name);
+	const found = Object.hasOwn(lookup, section) ? lookup[section] : void 0;
+	if (!found) return null;
+	const context = found.context ? `${found.context}\n\n` : "";
+	return `${COMMAND_NOTATION}\n\n${context}${found.body()}`;
+}
+function topicOwning(section) {
+	for (const name of topicNames()) if (Object.hasOwn(sectionLookup(name), section)) return name;
+	return null;
+}
+function renderIndex(version) {
+	const lines = [
+		`stim ${version} -- reference for the binary you are running.`,
+		"",
+		COMMAND_NOTATION,
+		"",
+		"This output is generated by the CLI, so it always matches this version.",
+		"The bundled skill routes coding agents to the agent topic. Other topics",
+		"carry the detailed command contracts and remedies.",
+		"",
+		"TOPICS"
+	];
+	const width = Math.max(...topicNames().map((n) => n.length));
+	for (const name of topicNames()) lines.push(`  ${name.padEnd(width)}  ${TOPICS[name]?.summary ?? ""}`);
+	lines.push("", "Read one with:  stim guide <topic>   (sectioned topics: stim guide <topic> <section>)");
+	return lines.join("\n");
+}
+function guideCommand(program, version) {
+	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((topic, section) => {
+		if (!topic) {
+			console.log(renderIndex(version));
+			return;
+		}
+		const body = renderTopic(topic);
+		if (!body) {
+			console.error(chalk.red(`Unknown topic "${topic}".`));
+			console.error(chalk.dim(`Available: ${topicNames().join(", ")}`));
+			const owner = topicOwning(topic);
+			if (owner) console.error(chalk.dim(`Did you mean: stim guide ${owner} ${topic}`));
+			process.exit(1);
+		}
+		if (!section) {
+			console.log(body);
+			return;
+		}
+		const index = renderSectionIndex(topic);
+		if (!index) {
+			console.error(chalk.red(`Topic "${topic}" has no sections.`));
+			process.exit(1);
+		}
+		const sectionBody = renderSection(topic, section);
+		if (!sectionBody) {
+			console.error(chalk.red(`Unknown section "${section}" in topic "${topic}".`));
+			console.error(index);
+			process.exit(1);
+		}
+		console.log(sectionBody);
+	});
+}
+//#endregion
+export { guideCommand as default, renderIndex, renderSection, renderSectionIndex, renderTopic, sectionLookup, sectionNames, topicNames };