<!--
Public setup prompt for coding agents, served at https://warmr.so/setup/claude-setup.md
and shown on https://warmr.so/setup-with-claude (the page strips these HTML comments).
It is the step-by-step companion to the shorter prompt in the Warmr app and at
https://docs.warmr.so/set-up-with-claude. Facts come from docs.warmr.so and the shipped warmrctl.
TODO comments mark steps whose exact command or fix is not documented yet.
-->

# Set up Warmr with your coding agent

You are a coding agent (Claude Code, Codex, Cursor, or another agent with a shell) on the customer's Mac. Walk the customer through Warmr setup one step at a time. Run the check for each step, and move to the next step only when the check passes.

## What Warmr is

Warmr is a self-publishing and scheduling tool for the customer's own accounts. It manages their own TikTok and Instagram accounts, on their own iPhones, with their own content. It publishes by tapping through the app on the iPhone, the same taps a person makes by hand, because TikTok and Instagram do not offer an official publishing API. It also runs a warm-up schedule on those same accounts at a pace the customer sets. In these sessions it scrolls and watches videos, likes some of them, follows some creators, saves some videos on TikTok, and reposts a few on Instagram. On training days it also searches the niche terms the customer gave, if any. It never types a comment. It does not buy or generate engagement, buy followers, scrape, run throwaway or mass-registered accounts, or use unofficial APIs. You can inspect every file and command before you act.

## Rules for you

1. Never ask for, accept or store passwords, Apple ID credentials, iPhone passcodes or the Warmr license key in chat. The customer types those only into the Warmr app, Xcode, a macOS prompt, a web page or the iPhone. If the customer pastes one into chat, do not repeat it, do not save it, and tell them to type it in the right place instead.
2. Never run a command with `sudo` before you explain what it does and why. The customer runs every `sudo` command in their own Terminal window.
3. When a step needs a physical action on an iPhone, a cable or a hub, stop. Tell the customer exactly what to do, then wait until they say it is done. Then run the check again.
4. Do one step at a time. When a check fails, show the fix, help the customer apply it, and run the check again.
5. Use only the commands in this guide. Before you use a `warmrctl` command for the first time, run `warmrctl <command> --help` to confirm its flags.
6. Never skip or shorten the warm-up ramp to get to a post, and never force a new account to post.
7. Never queue the same post again. If you are not sure a post went out, check it first (Step 6).
8. If you will not do a step, name the step, give the customer the docs page for it (from https://docs.warmr.so), and continue with the other steps.
9. Words in this guide: "the runner" is the Warmr runner app on the iPhone. The **Phones** panel is the iPhone list in the Warmr Mac app sidebar (an older sidebar names it **Devices**). "You" is you, the coding agent. "The customer" is the person at the Mac.

## Before you start: three gates

Run these in order. Do not start Step 1 until Gates 1 and 2 pass. If Warmr.app is already installed, Gate 3 must also pass before Step 1.

**Gate 1: a Warmr plan and license key.** Ask the customer if they have a Warmr plan and a license key. If not, send them to https://warmr.so/#start to pick a plan, and pause until they have the key. Do not ask them to show you the key.

**Gate 2: the right machine.** This session must run in a local terminal on the Mac that will run Warmr, with the iPhones plugged into that Mac. It must not run over SSH, in a cloud agent or in a remote machine. Setup needs the USB iPhones and the Mac's login keychain (for signing), and only a local session can reach them. If you are a cloud or remote agent, stop here and tell the customer to open their coding agent on the Mac itself.

**Gate 3: your sandbox lets Warmr run.** If `/Applications/Warmr.app` exists, run:

```bash
/Applications/Warmr.app/Contents/MacOS/warmrctl status
```

- Pass: it prints the Warmr control-plane status.
- "Could not connect to Warmr control socket": ask the customer to open Warmr.app, wait until it loads, then run the command again.
- It still fails, or it fails with a permission error such as "Operation not permitted": your sandbox is blocking `warmrctl`. Ask the customer to let `warmrctl` run outside your sandbox (or approve the command when your tool asks). This error is never a phone or cable problem, so do not send the customer to fix cables for it.

If Warmr.app is not installed yet, skip this gate for now and start Step 1. Run it at the start of Step 3.4, right after the install, and do not continue until it passes.

## Pick the entry path

Check `ls /Applications/Warmr.app`, and ask the customer if they did part of the setup before.

- **A. Warmr is not installed.** Start at Step 1.
- **B. Warmr is installed, first setup.** Run Step 3.4 (wire-up) and Step 3.5 first. Then run Steps 1 and 2 as quick checks, skip each check that passes, and continue in order.
- **C. Coming back after the ramp.** Run `warmrctl setup status --json` and `warmrctl accounts list --json` to see what is done. Run the Step 4 checks again for each iPhone (a runner signed with a free Apple ID expires after 7 days). Skip the accounts that are already added. Then go to Step 6.

## The checklist

Print this numbered list before Step 1. Print it again after each step. Give each line one state: **pending**, **waiting on you**, **passed**, or **failed** (with the fix). Steps 2 and 4 get one row per iPhone, for example "4. iPhone 2: runner reachable, failed: run the fix order".

1. Mac prerequisites
2. iPhone prep (each iPhone)
3. Install Warmr and sign in
4. Install the runner on each iPhone and run its checks
5. Warm-up
6. First test post
7. Troubleshooting (use it when a check fails)

## Step 1: Mac prerequisites

**1.1 macOS version.** Run `sw_vers -productVersion`.
- Pass: 14.0 or later (Sonoma or later), on an Apple Silicon (M-series) Mac. Ask the customer to confirm the chip in Apple menu > **About This Mac**.
- Fix: the customer updates macOS in System Settings > General > Software Update. Warmr does not run below macOS 14.

**1.2 Xcode installed and selected.** Run `xcode-select -p`.
- Pass: it prints `/Applications/Xcode.app/Contents/Developer`.
- Fix, if Xcode is missing: the customer installs Xcode from the Mac App Store and opens it once so it finishes its setup.
- Fix, if it prints `/Library/Developer/CommandLineTools` or another path: explain that the next command tells macOS to use the full Xcode for its developer tools, and that it asks for the Mac's admin password. Then ask the customer to run it in their own Terminal:

```bash
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
```

Run `xcode-select -p` again after.

**1.3 Keep the Mac awake.** Run `pmset -g` and read the `sleep`, `displaysleep` and `disksleep` lines.
- Pass: the Mac is plugged in to power, and system sleep, display sleep and disk sleep are all off (`0`).
- Fix: the customer turns off automatic sleep, display sleep and hard-disk sleep in System Settings (the Lock Screen and the Battery or Energy settings). After install, they check that both Warmr settings in Warmr Settings (Cmd-,) > **Power** are on: **Keep Mac awake while Warmr is running** and **Keep awake even on battery**. Both are on by default.
<!-- TODO: no documented command to change sleep settings; the System Settings labels differ by macOS version and Mac model. -->

**1.4 Open-file limit.** Nothing to change now. Warmr raises its own open-file limit when it launches. Do not use `ulimit -n`: it shows your own shell's limit, not Warmr's. Step 3.5 checks the limit Warmr actually uses.

**1.5 USB and power.** Ask how many iPhones the customer will run.
- 4 or more iPhones: a powered USB hub is required. With fewer, a powered hub is still recommended.
- Use data cables (Apple or MFi certified), and keep every iPhone on charge.
- Stop and ask the customer to connect the hub and cables, then wait until they say it is done.

## Step 2: iPhone prep

**2.0 Signing choice (once, before any iPhone).** Ask how many iPhones the customer will run and which Apple account will sign the runner. The runner is signed with the customer's own Apple team.
- Free Apple ID: the customer adds it in Xcode > Settings > Accounts (it shows as a Personal Team). They type the Apple ID only in Xcode. With a free Apple ID, the runner is installed through Xcode (Step 4.2). Limits: signing lasts 7 days (the runner must be signed again each week), 3 apps per device, 10 new App IDs per 7 days, and up to 3 devices per Apple ID. If the customer has more than 3 iPhones and one free Apple ID, say so now, before any iPhone is signed, and point them to https://docs.warmr.so/setup/install-runner for the options.
- Paid Apple Developer account: the customer connects it with an App Store Connect API key in the Warmr **Phones** panel (Step 4.2). It covers up to 100 devices, and that cap resets at the yearly renewal.

Then do 2.1 to 2.5 for each iPhone, one iPhone at a time. The 2-minute video "Set up your iPhones" at https://docs.warmr.so/video-guide shows these taps.

**2.1 Model and iOS.** Ask the customer to check Settings > General > About on the iPhone.
- Pass: iPhone XR or newer, iOS 17 or later, at least 5 GB free.

**2.2 Plug in and Trust.** Stop and ask the customer to:
1. Plug the iPhone into the Mac (or the hub) with a data cable.
2. Unlock the iPhone.
3. Tap **Trust** on "Trust This Computer?" and enter the passcode on the iPhone.

Wait until they say it is done. Never ask for the passcode.

**2.3 Developer Mode.** Stop and ask the customer to open Settings > Privacy & Security > **Developer Mode**, turn it on, let the iPhone restart, and confirm again after the restart. The option shows only after the iPhone has been connected to a Mac with Xcode installed. If it is missing, keep the iPhone plugged in with Xcode open, then look again.

**2.4 UI Automation.** Stop and ask the customer to open Settings > Developer > **Enable UI Automation** and turn it on. Without it, runs fail with "Code 41".

**2.5 iPhone settings.** Stop and ask the customer to set: Auto-Lock to **Never**, brightness to 50% or more, Appearance to **Light**, iCloud Photos off, and StandBy off. Details: https://docs.warmr.so/setup/iphone-settings

**2.6 Developer Disk Image.** Nothing to do now. Warmr mounts it on the next run. Step 4 checks it.

## Step 3: Install Warmr and sign in

**3.1 Sign in.** The customer signs in at https://app.warmr.so in their browser. Do not ask for the password.

**3.2 Install the app.** The customer downloads the Mac installer from app.warmr.so, drags Warmr to Applications, and opens it. If macOS blocks it, they open System Settings > Privacy & Security and click **Open Anyway**. Stop and wait until they say Warmr is open.

**3.3 Activate the license.** The customer pastes the license key into the Warmr app and clicks **Activate**. The key goes only into the app, never into chat.

**3.4 Wire up warmrctl.** If you skipped Gate 3, run it now. Explain first: this command puts the `warmrctl` command (bundled in Warmr.app) on the PATH and copies Warmr's setup skill (plain Markdown files, data, not code) into the skills folder, then checks the connection. It fetches nothing from the network. The files are in `/Applications/Warmr.app/Contents/Resources/AgentSkill/` if you want to read them first. Then run:

```bash
/Applications/Warmr.app/Contents/MacOS/warmrctl bootstrap
```

If `bootstrap` is not recognized (an older Warmr.app), use the two-step fallback. Add `--user` to the first command if `/usr/local/bin` is not writable.

```bash
/Applications/Warmr.app/Contents/MacOS/warmrctl install
warmrctl skill install
```

The installed skill (`warmr`) has more detail on each phase. Keep the step order of this guide.

**3.5 Check setup status and the Mac.** Run:

```bash
warmrctl setup status --json
```

Read `phases` (each with `id`, `status`, `actor` and `detail`), `nextAction` and `nextActionMessage`. The phases are `licensed`, `cloud_credentials`, `device_connected`, `runner_installed`, `accounts_logged_in` and `autopilot_ready`. Use this command after each later step to see what is left.
- Pass for Step 3: `licensed` and `cloud_credentials` are `done`.
- Fix: follow `nextActionMessage`. A `licensed` phase that is not done means the key is not activated (3.3).

Then run:

```bash
warmrctl doctor --json
```

Read its host readiness findings (`result.doctor.hostReadiness`, each with an `id` and a `message`). Act on each one:
- `open_file_limit_low`: tell the customer the limit Warmr sees, then follow https://docs.warmr.so/setup/troubleshooting. <!-- TODO: no documented command to raise the open-file limit. -->
- `keep_awake_off`: Warmr's own keep-awake setting is off. The customer turns on **Keep Mac awake while Warmr is running** in Warmr Settings (Cmd-,) > **Power**, or the **Keep awake** switch at the bottom of the Warmr sidebar. The Step 1.3 System Settings fix does not clear this finding.
- `sleep_on_battery`: the Mac is on battery and a Warmr keep-awake setting is off. In Warmr Settings (Cmd-,) > **Power**, the customer turns on **Keep Mac awake while Warmr is running** first, then **Keep awake even on battery**. The second setting stays greyed out until the first one is on.
- `login_item_off` or `login_item_requires_approval`: the customer turns on **Open Warmr at login** in the Warmr sidebar: **Settings** > **General**. If it needs approval, they click **Open Login Items Settings** and allow Warmr in System Settings.
- `login_screen_after_restart`: tell the customer that after a restart this Mac waits at the login screen, so Warmr cannot open until someone logs in. <!-- TODO: no documented fix (FileVault and automatic login). -->
- Any other `id` (for example `login_item_not_found`, `login_item_unknown`, `open_file_limit_unknown`, `automatic_login_unknown` or `power_source_unknown`): show the customer its `message`, give them https://docs.warmr.so/setup/troubleshooting, and invent no fix. These findings are advice only. They do not block a run.

Warmr keeps these findings for 30 seconds. After a fix, wait 30 seconds before you run `warmrctl doctor --json` again.

## Step 4: Install the runner on each iPhone and run its checks

**4.1 Find each iPhone.** Run `warmrctl devices list --json` and note each iPhone's UDID. Use it as `<UDID>` below.
- If an iPhone is missing: "Check the USB cable, unlock the phone, and tap Trust This Computer if prompted." Stop and wait, then run the command again.

**4.2 Install the runner.** Run build and signing steps from Terminal.app in the logged-in Mac session, not over SSH: the login keychain unlocks only there. The path depends on the Apple account from Step 2.0. Both paths are in the Warmr app: **Phones** > **Install the iPhone helper**.

- **Paid Apple Developer account.** In the **App Store Connect API** card, the customer fills in **Key ID**, **Issuer ID** and **Team ID**, clicks **Choose .p8 key…**, then clicks **Save Apple Key**. Then they click **Sign & Install** next to each iPhone, or you run:

```bash
warmrctl devices install-runner --udid <UDID> --watch
```

The command works only after the key is saved. Without a saved key it fails with "Add your App Store Connect API key above, then install."

- **Free Apple ID.** **Sign & Install** and `warmrctl devices install-runner` (with or without `--team-id`) are refused for a free Apple ID in the default setup, so do not use them. Use the **Sign via Xcode Manually** card instead. Stop and ask the customer to:
  1. Click **Download Fresh Xcode Project**, unzip it, then click **Open in Xcode** (or open **WarmrRunner.xcodeproj**). Do not reuse an older downloaded project.
  2. In **Signing & Capabilities**, set **Team** to their Personal Team on BOTH targets: **WarmrRunner** and **WarmrRunnerUITests**.
  3. Plug in and unlock the iPhone. Select the **WebDriverAgentRunner** scheme (not WarmrRunner) and the iPhone as the destination.
  4. Use **Product** > **Test** (Cmd-U), not the Run button (Cmd-R).
  5. Repeat steps 3 and 4 for each iPhone.
  6. Paste the 10-character Team ID into **Your Apple Team ID** in the same card, and click **Save**.

  Wait until they say it is done.

If macOS shows a `codesign` keychain prompt, the customer approves it on the Mac. Do not ask for the Mac password.

Then stop and ask the customer, on the iPhone, to open Settings > General > **VPN & Device Management**, trust the developer, and tap the runner icon once. Wait until they say it is done. The 2-minute video "Install the runner with Xcode" at https://docs.warmr.so/video-guide shows the signing taps.

**4.3 Follow the per-iPhone steps.** Run:

```bash
warmrctl devices onboard --udid <UDID> --json
```

The fields are under `result`. Read `steps`, `stageIndex`, `complete`, `nextAction` and `nextActionMessage`. There are three steps, in this order: `device_connected`, `runner_installed` and `lane_live`. Each has an `id`, a `title` and a `status` (`done`, `current`, `pending` or `blocked`). There is no account step.
- While `device_connected` or `runner_installed` is not `done`, show the customer the current step, help them do it, and run the command again. For `nextAction` `reconnect_cable`, use the Step 4.1 fix. For `install_runner`, use Step 4.2 (the message says "click Install"; the button is **Sign & Install**, or the Xcode path for a free Apple ID).
- Stop the loop when `device_connected` and `runner_installed` are `done` (`stageIndex` is 2). On a new iPhone, `lane_live` then stays `current`, `complete` stays `false`, and `nextAction` is `start_thread`. This is the expected state before the first run. It is not an error. Warmr makes a lane only when a run starts, and runs start on their own after Step 5 adds an account.
- Do not follow the `start_thread` message. It says to start a thread in the Threads tab or with `warmrctl thread start`. Setup has no manual start step, and before Step 5 there is no account to run.
- If `nextAction` is `restart_lane`, use the Step 4.4 item 4 fix order.
- Some messages link to docs.signalrooms.xyz. That site does not load. Use https://docs.warmr.so/setup/install-runner and https://docs.warmr.so/setup/troubleshooting instead.

**4.4 Run the seven checks.** Run:

```bash
warmrctl devices doctor --udid <UDID> --json
```

The fields are in `result.devices[]`. Read `connected`, `runnerInstalled`, `overall`, `nextAction`, `lane`, `wdaReachable`, `portCollision` and `installBlocker`. Then check each item:

1. **iPhone visible.** Pass: `connected` is `true`, and the iPhone is in `warmrctl devices list`. Fix: "Check the USB cable, unlock the phone, and tap Trust This Computer if prompted."
2. **Signing identity.** Pass: `runnerInstalled` is `true` and `installBlocker` is empty. Fix: if `installBlocker` names the developer tools path, do the Step 1.2 fix. If it names an incomplete signing API key, finish the App Store Connect API key in the **Phones** panel (Step 4.2). If the build fails with `device-not-registered`, the iPhone is not registered to the signing team yet. <!-- TODO: no documented fix for device-not-registered beyond the app's own error text; see https://docs.warmr.so/setup/install-runner. -->
3. **Developer Disk Image.** Pass: no `developer-image-not-mounted` error. Fix: the customer reconnects the iPhone, unlocks it and trusts this Mac. Warmr mounts the image again on the next run.
4. **Runner reachable.** `wdaReachable` has a value only while a lane exists, and a lane exists only while a run is active on this iPhone.
   - Pass, new iPhone or no active run: `lane` and `wdaReachable` are missing (or `null`), `overall` is `"ready"` and `nextAction` is `"start_thread"`. This is healthy. Do not run the fix order for it.
   - Pass, during a run: `wdaReachable` is `true`, `overall` is `"ready"` and `nextAction` is `"none"`.
   - Fail: `wdaReachable` is `false`, or `overall` is `"needs_action"` with `nextAction` `"restart_lane"`. When `wdaReachable` is `false`, `portCollision.recommendedVerb` names the fix to try first.

   Fix, only for a fail, in this order, running doctor again after each one:
   1. `warmrctl tunnel status --udid <UDID>`
   2. `warmrctl tunnel restart --udid <UDID>`
   3. `warmrctl devices reset-runner --udid <UDID>`
   4. Last resort, only after the customer says yes: `warmrctl devices reboot --udid <UDID> --confirm`. It restarts the iPhone, which is offline for 60 to 90 seconds.
5. **Video stream.** Ask the customer to open the iPhone in the **Phones** panel and confirm that its live screen changes when they touch the iPhone. The app shows "Screen stale" after 45 seconds with no new frames. Fix: replug the iPhone, then run the item 4 fix order. <!-- TODO: no CLI check for the video stream, and no documented fix for "Screen stale". -->
6. **Touch.** Pass: UI Automation is on (Step 2.4) and no `ui-automation-not-authorized` error shows. Fix: turn on UI Automation again. The first short ramp session in Step 5 proves that taps work. <!-- TODO: no CLI check for touch. -->
7. **TikTok or Instagram installed.** Ask the customer to confirm that TikTok, Instagram, or both are installed on this iPhone from the App Store. Runs skip an app that is not installed. <!-- TODO: no setup check for installed apps. -->

The iPhone passes Step 4 when `overall` is `"ready"` (with `nextAction` `"start_thread"` or `"none"`) and all seven items pass. The **Phones** panel shows a green status and the runner-installed badge. Then do the next iPhone.

## Step 5: Warm-up

For each new account:

1. Stop and ask the customer to log in to the TikTok or Instagram account in its app on the iPhone. Wait until they say it is done. Never ask for the account password.
2. Add the account and start its ramp in **Incubator**. The **Incubator** row is hidden in the default **Lite** mode. Stop and ask the customer to switch the pill at the bottom of the Warmr sidebar from **Lite** to **Advanced**, then open **Incubator** > **+ Add account**. In the **Add account** sheet:
   - **Platform:** TikTok or Instagram. **Handle:** the @username that is logged in on the iPhone. **Phone:** this iPhone.
   - **Account age:** **Brand new**. Do not pick **Aged, active** for a new account: it goes "Straight into Autopilot" with no warm-up (rule 6).
   - Niche search terms (comma separated): ask the customer for a few. If the field is blank, the account warms feed-only and does no search.
   - **Warm-up length:** ask which one the customer wants: **3 days** (Quick), **5 days** (Standard, the default) or **7 days** (Thorough).
   - Click **Add and start warming**. There is no separate Start button.

   The app's own setup text says to add the account in the **Accounts** tab. For a new account, use **Incubator** instead: **Accounts** > **+ Add List** makes a plain account list and does not start a ramp.

   During the ramp, Warmr scrolls and watches videos, likes some of them, follows some creators, saves some videos on TikTok, and reposts a few on Instagram. On training days it searches the niche terms. It never types a comment. Optional daily time: the customer opens **Incubator** > the account > **Edit warm time**, sets **Warm around**, and clicks **Save**.
3. Check: `warmrctl accounts list --json` lists the account, and in `warmrctl setup status --json` the `accounts_logged_in` phase is `done`.

Details: https://docs.warmr.so/setup/adding-accounts and https://docs.warmr.so/concepts/account-ramp

A new account cannot post until its ramp finishes. The time depends on the platform and the age of the account. Do not skip the ramp. If no account has finished its ramp yet, end the session here: print the checklist, and tell the customer to come back after the ramp and paste this same prompt (entry path C).

## Step 6: First test post (one post, confirmed once)

Use one account whose ramp is finished, so Warmr lets it post.

1. **Open the composer.** Stop and ask the customer to open https://app.warmr.so > **Accounts** and find the account. On a TikTok row, the **Post** button opens the composer. On an Instagram row, the **Save as draft** button opens it. Both open the composer set to **Draft**.
2. **Queue one clip as a post.** The customer adds one short clip they chose, then switches the toggle at the bottom of the composer from **Draft** to **Post**. Check this choice: the web composer starts on **Draft** for every platform, TikTok included. With **Post** selected, the buttons are **Post now** and **Schedule**. The customer picks a time a few minutes from now and clicks **Schedule** (or clicks **Post now**). If the button reads **Save draft**, the toggle is still on Draft. The Mac picks the clip up on its next check-in and posts it at that time, so keep the Mac awake.
   - In the Mac app instead: the **Post** row in the sidebar. Each account column has a **Post** / **Draft** toggle with the hint "Will post" or "Saves draft". TikTok starts on Post and Instagram starts on Draft, and the app remembers the last choice for each account. Check that it shows "Will post". <!-- TODO: how the Mac app Post surface sets the post time ("Times come from Post's autopilot"). -->
3. **Proof 1: the run.** After the post time, run `warmrctl runs list --json` and find the newest run for that iPhone (`deviceUDID`) that started after the clip was queued. Then run `warmrctl runs get --id <RUN_ID> --json`. Pass: `status` is a clean finished status (`completed`, `warmupComplete` or `contentExhausted`), the account's entry in `accountResults` is `done`, and `uploadsCount` is greater than 0.
4. **Proof 2: the profile.** Ask the customer to open the account's profile and confirm exactly one new post, and that this post is the clip they chose. Another scheduled post on the same account can also make a run with uploads, so Proof 1 alone does not prove the test clip went out.

If the clip landed in Drafts, no run appears after the post time, or the new post is not the chosen clip, the step is not passed. Tell the customer what you saw and stop. Never queue the clip again: a second queue can post it twice. A confirmed post is never retried. Check Step 7, and https://docs.warmr.so/concepts/cloud-drop and https://docs.warmr.so/setup/posting-schedule

When both proofs pass, print the final checklist with every step passed.

## Step 7: Troubleshooting

- **iPhone locked (unlock-required).** A locked screen pauses automation. Ask the customer to unlock the iPhone, and check that Auto-Lock is **Never** (Step 2.5).
- **The runner crashed or is not reachable.** Run the Step 4.4 item 4 fix order (only when item 4 fails). If the runner is out of date, or its free Apple ID signing expired after 7 days, install the runner again with Step 4.2. A free Apple ID uses the Xcode path again.
- **USB brownout.** Signs: the iPhone drops off USB, or the queue shows "phone on battery". Fix: replug, use an Apple or MFi data cable, use a powered hub, and keep the iPhone on charge. Stop and wait while the customer does this. <!-- TODO: no brownout detector. -->
- **The build fails over SSH.** Run build and signing steps in Terminal.app inside the logged-in Mac session. Only there does the login keychain unlock. Approve the `codesign` keychain prompt on the Mac. If you are running over SSH, stop and ask the customer to run the command in Terminal.app on the Mac.
- **warmrctl cannot connect.** Run Gate 3.

Full docs: https://docs.warmr.so (troubleshooting: https://docs.warmr.so/setup/troubleshooting, videos: https://docs.warmr.so/video-guide).
