Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Add the vphone-guest-control skill and an agent install prompt

Lakr66148f3c3e27
diff --git a/README.md b/README.md
index 07e5dd86..f2903aa5 100644
--- a/README.md
+++ b/README.md
@@ -39,6 +39,23 @@ Launchpad downloads the firmware, patches it, restores the system, and boots the
To install a package manager in the VM, see [Package Environment](Documents/Guides/package-environment.md).
+### Let an agent do it
+
+If you use a coding agent (Claude Code, Codex, or similar) on this Mac, paste the prompt below instead of following the steps by hand. The agent reads the vphone skill, checks what is already set up, installs Launchpad and `VPhone.bundle`, and stops to ask when a step needs you, such as an administrator password or a change in macOS Recovery.
+
+```text
+Set up vphone on this Mac. Read the skill at
+https://raw.githubusercontent.com/Lakr233/vphone-cli/main/Skills/vphone-guest-control/SKILL.md
+and the files it links under references/ (same folder), then follow them:
+install the newest notarized vphone-launchpad (not every release has a
+-notarized zip), put
+vphone-launchpad-cli on PATH, install the VPhone.bundle that matches
+Launchpad's series, and check `vphone-launchpad-cli status`. Do not change SIP,
+boot-args or any other host security setting, and do not create a machine
+until I confirm the firmware and the free disk space. When a step needs me,
+tell me exactly what to do and wait.
+```
+
## Command Line
Launchpad drives VMs through the `vphone-cli` inside `VPhone.bundle`. You can also run it in Terminal:
diff --git a/Skills/vphone-guest-control/SKILL.md b/Skills/vphone-guest-control/SKILL.md
new file mode 100644
index 00000000..97beb259
--- /dev/null
+++ b/Skills/vphone-guest-control/SKILL.md
@@ -0,0 +1,91 @@
+---
+name: vphone-guest-control
+description: Install vphone-launchpad and VPhone.bundle, create and run vphone virtual iPhones, and drive a running guest from the command line with vphone-launchpad-cli and the per-machine vphone.sock. Make sure to use this skill whenever the user mentions vphone, vphone-launchpad, vphone-launchpad-cli, VPhone.bundle, vphoned, vphone.sock, or a virtual iPhone on their Mac, even if they do not name the tool. That includes setting vphone up, creating/starting/stopping a machine, tapping/swiping/typing/taking screenshots in the guest, calling a vphoned method (apps, files, logs, processes, UI tree), installing an IPA into a guest, installing the roothide/rootless bootstrap (Irisin), ssh into a guest, installing a .deb, or debugging a guest that shows a black screen or will not boot to the UI.
+---
+
+# Driving vphone
+
+vphone runs a virtual iPhone on an Apple Silicon Mac through
+Virtualization.framework. Two pieces matter to you:
+
+| Piece | Role |
+| --- | --- |
+| `vphone-launchpad` (Mac app) | Downloads and verifies `VPhone.bundle`, creates machines, runs them. Owns the only root helper. |
+| `vphone-launchpad-cli` | A stateless client of the running app. Every command also appears in the app's window and history. |
+
+Use `vphone-launchpad-cli` for everything. The app does the privileged and
+signed work for you; a second route (sudo, a copy of `vphone-cli`, `devicectl`)
+either lacks the entitlements, bypasses the checks the app records, or times out
+against these guests.
+
+## How a session should go
+
+1. **Find out where the user is.** Run `vphone-launchpad-cli status`. If the
+ command does not exist, go to [install](references/install.md). Otherwise the
+ JSON tells you the next step:
+ - `canInstallBundles: false` or `helper` not `ready`: the user must finish
+ Host Setup in the app (administrator password, Developer Tools access).
+ You cannot do this for them; say exactly what is missing.
+ - `activeBundle: null` or `bundleReady: false`: install or verify a bundle.
+ - `machines: 0`: create one ([machines](references/machines.md)).
+ - Otherwise: list machines, start the one the user named, then control it.
+2. **Pick the reference for the task, and read it before acting.**
+
+ | Task | Read |
+ | --- | --- |
+ | Install Launchpad or a bundle, host requirements, series matching | [references/install.md](references/install.md) |
+ | An install step failed: "damaged", Developer Tools access turns off, several macOS installations, `zsh: killed`, not Apple silicon | [references/install-faq.md](references/install-faq.md) |
+ | Create, start, stop, retry, update a machine | [references/machines.md](references/machines.md) |
+ | Tap, swipe, key, screenshot, anything on `vphone.sock` | [references/guest-socket.md](references/guest-socket.md) |
+ | Call a vphoned method: apps, files, logs, UI tree, processes | [references/rpc-methods.md](references/rpc-methods.md) |
+ | Installing an IPA | [references/rpc-methods.md](references/rpc-methods.md#installing-an-app) |
+ | roothide vs rootless, installing the bootstrap, ssh, `/rootfs`, handing files to vphoned, `.deb` | [references/guest-layout.md](references/guest-layout.md) |
+ | Black screen, timeouts, AMFI, "客体代理未连接" | [references/troubleshooting.md](references/troubleshooting.md) |
+ | A symptom the above does not cover; which research note or source explains it | [references/finding-docs.md](references/finding-docs.md) |
+
+3. **Verify with the guest, not with assumptions.** After an input, take a
+ screenshot or read `ui.describe`; after a launch, check `apps.foreground`.
+ The guest is a real device with timing, so a command that returned `ok` has
+ not necessarily produced the visible result.
+
+## Output and errors
+
+- Progress lines go to **stderr** as they arrive. The result is **one JSON
+ document on stdout**. Exit 0 is success; exit 1 is failure with the reason on
+ stderr. Parse stdout, and read stderr when the exit code is 1.
+- `vphone-launchpad-cli help` prints every command with its options and is
+ authoritative if this skill and the installed version disagree.
+- Quote JSON in single quotes: `guest rpc myphone apps.launch '{"bundle_id":"com.apple.Preferences"}'`.
+- Interrupting the CLI cancels `exec`, waits and CFW install. A bundle install
+ or a machine creation belongs to the app window and keeps going, so do not
+ start a second one because the CLI went quiet; run `vm log <name> --kind create`.
+- Pass `--root <library>` only when two libraries hold a machine with the same
+ name; the error lists the libraries.
+
+## Rules that save the user's machine
+
+These exist because each one has cost the user real time or disk before.
+
+- **Use the machines the user named.** Do not `vm create` to reproduce a
+ problem; diagnose on the existing guest. A creation takes tens of GB and
+ several restarts, and a half-built machine is harder to clean up than the bug.
+- **Creating is one at a time, after checking free disk.** IPSWs plus the
+ restore tree are large, and a full disk fails halfway with confusing errors.
+- **Never change host security settings** (SIP, boot-args, AMFI, Research
+ Guests) and never run `bundle accept`, `bundle remove`, `cfw install` or a
+ second `vm create` over existing work unless the user asked. Report what is
+ needed; the Mac's owner decides.
+- **`force` methods need the user's intent.** `processes.kill`, `services.stop`,
+ `apps.uninstall`, `system.respring`, `system.reboot` and similar refuse to run
+ without `"force":true`. Passing it is the confirmation, so pass it only for an
+ action the user asked for.
+- **Do not edit a machine's folder (`~/.vphone/machines/<name>/`) while it runs.**
+ Use RPC for guest files instead.
+- **Keep the host API listener on loopback.** `--api-listen` sends its token in
+ clear text.
+- **Install apps through installd** (`ideviceinstaller`) when the point is to
+ test installation; `apps.install` bypasses installd. Never use
+ `xcrun devicectl` to install or launch (it times out); listing devices is fine.
+- **When stuck, read before experimenting.** The repository's guides and
+ `Research/` notes quote real failures; see
+ [references/finding-docs.md](references/finding-docs.md).
diff --git a/Skills/vphone-guest-control/evals/evals.json b/Skills/vphone-guest-control/evals/evals.json
new file mode 100644
index 00000000..8e4db0ec
--- /dev/null
+++ b/Skills/vphone-guest-control/evals/evals.json
@@ -0,0 +1,29 @@
+{
+ "skill_name": "vphone-guest-control",
+ "evals": [
+ {
+ "id": 1,
+ "prompt": "I just downloaded vphone-launchpad 2.2.3 on a fresh Mac. Get me from here to a running machine called test01 using the newest firmware you can find. Show me the exact commands you would run and in what order; do not run them.",
+ "expected_output": "Checks status first; links the CLI; installs a 2.2.x bundle (not a newer series); checks disk; vm create without hard-coded IPSWs (catalog default) or with explicit ones; vm start --wait; does not touch SIP/boot-args; mentions the admin password prompt.",
+ "files": []
+ },
+ {
+ "id": 2,
+ "prompt": "myphone is running. Open Settings, tell me what the screen shows, then read /etc/hosts from the guest. Show me the commands you would run; do not run them.",
+ "expected_output": "Uses guest rpc apps.launch with bundle_id com.apple.Preferences, a screenshot to a file or ui.describe/ui.ocr (not the attached grayscale image), files.read for /etc/hosts; no ssh, no devicectl.",
+ "files": []
+ },
+ {
+ "id": 3,
+ "prompt": "myphone boots to a black screen but I can hear it is running. Plan how you would diagnose it. Do not create any new machines.",
+ "expected_output": "processes.list for SpringBoard, logs.crashes, reads the datamigrator stackshot, follows turnstileInfo, points at Research/Patches/hv_vmm_present_usermode_xrefs.md and Documents/Guides/troubleshooting.md; does not vm create to reproduce; stops and reports rather than changing host settings.",
+ "files": []
+ },
+ {
+ "id": 4,
+ "prompt": "I want ssh into myphone and a debuggable test IPA installed. It was just created. How do you do that, and where do I put the IPA so vphoned can read it?",
+ "expected_output": "Notes a fresh guest has no sshd; installs the roothide bootstrap (bootstrap.install or Apps > Install Bootstrap), then installs apt, bash, uikittools, launchctl, openssh-server together via Irisin Bootstrap Install; iproxy + ssh mobile; ssh lands in the jbroot, real root is /rootfs; scp to /tmp then mv to /rootfs/private/var/tmp and apps.install with /private/var/tmp/<file>; warns apps.install deletes the file.",
+ "files": []
+ }
+ ]
+}
diff --git a/Skills/vphone-guest-control/references/finding-docs.md b/Skills/vphone-guest-control/references/finding-docs.md
new file mode 100644
index 00000000..46a794ea
--- /dev/null
+++ b/Skills/vphone-guest-control/references/finding-docs.md
@@ -0,0 +1,103 @@
+# Where to look when something goes wrong
+
+The repository holds the evidence behind almost every behavior. Reading the
+right note is faster and safer than experimenting on the user's machine, and
+many notes record the exact symptom, the cause and the fix. Paths are relative
+to the vphone-cli repository root. If you have no checkout, read the same files
+at <https://github.com/Lakr233/vphone-cli> (`Documents/`, `Research/`).
+
+Order of preference: **the user guides** (current instructions) first, then
+**`Research/`** (evidence and history, may mention retired commands), then the
+**source**, then `git log`. `Research/` notes say so when they describe an
+earlier experiment; trust `vphone-launchpad-cli help` and the guides over a
+note's command lines.
+
+## Contents
+
+- By symptom
+- By subject
+- Searching
+- Source layout
+- When to stop and report
+
+## By symptom
+
+| Symptom | Start with |
+| --- | --- |
+| `vphone-vm` killed before a window opens; AMFI; "Research Guests" | `Documents/Guides/host-setup.md`, `Documents/Guides/troubleshooting.md`, `Research/Host/macos27_m6_amfi.md` |
+| Launchpad/bundle version mismatch, which Launchpad is notarized | `Documents/Downloads/README.md`, `Documents/Guides/bundle-integration.md` |
+| `vm create` failed at a step; restore or DFU trouble | `Documents/Guides/create-and-run.md`, `Documents/Guides/compatibility.md`, `Research/Restore/native_restore_architecture.md`, `Research/Restore/virtual_dfu_probe.md` |
+| Which iPhone IPSW pairs with which cloudOS | `Documents/Guides/compatibility.md`; `vphone-cli fw catalog` (via `exec`) for what exists now |
+| Guest boots to a black screen or loops | `Documents/Guides/troubleshooting.md`, `Research/Patches/hv_vmm_present_usermode_xrefs.md`, `Research/Kernel/kernel_jb_patch_notes.md` |
+| `EXC_GUARD` / `GUARD_TYPE_MACH_PORT` in an app | `Documents/Guides/troubleshooting.md`, `Research/KernelCustomFirmwarePatches/README.md` |
+| No package manager, no ssh, bootstrap install | `Documents/Guides/package-environment.md`, [guest-layout](guest-layout.md), `Research/Guest/roothide_bootstrap_base.md` |
+| `dyld ... @loader_path/.jbroot/...` crash, `sudo` fails to load a library | `Research/roothide_loader_links.md` |
+| ssh closes at once or `PAM: initialisation failed`, "no such user" | `Research/Guest/roothide_bootstrap_base.md` (open issues section) |
+| An RPC method's parameters, errors, or capability flags | `Research/vphoned_http_api.md` ("Method catalog", "HTTP and WebSocket contract") |
+| The host API listener, token, 401/403/415 | `Research/vphoned_http_api.md` ("Access control") |
+| Taps or swipes land in the wrong place; gestures; keyboard | `Research/Guest/trackpad_gesture_mapping.md`, `Research/Guest/keyboard_event_pipeline.md` |
+| Skipping Setup Assistant, device state after boot | `Research/Guest/setup_assistant_skip.md` |
+| Developer Mode, DDI mount errors | `Research/Guest/devmode_xpc_protocol.md` |
+| App install fails, signature, profile checks, UDID | `Research/Guest/xcode_install_signature_gate.md` |
+| Location simulation returns `unavailable` | `Research/Guest/location_simulation_26_4_failure.md` |
+| Camera / virtual camera | `Research/Guest/virtual_camera_transport.md` |
+| Machine identity, clone behaving like the same device | `Research/Guest/machine_identifier_storage_analysis.md` |
+| What a patch does, whether it is on, why a preset differs | `Research/0_binary_patch_comparison.md`, `Research/KernelCustomFirmwarePatches/README.md` |
+| Which binary does what in the bundle | `Research/Host/host_binary_split.md`, `Documents/Guides/bundle-integration.md` |
+| Launchpad command line | `Documents/Guides/launchpad-cli.md` |
+
+## By subject
+
+- **User guides** (`Documents/Guides/`): `host-setup`, `create-and-run`,
+ `compatibility`, `troubleshooting`, `package-environment`,
+ `bundle-integration`, `launchpad-cli`. `Documents/README.md` indexes them.
+- **Research index:** `Research/README.md` lists every note by subject
+ (firmware, kernel, restore, host, guest, history).
+- **Patch inventory:** `Research/0_binary_patch_comparison.md` is canonical for
+ what each patch changes.
+- **Kernel evidence:** `Research/Kernel/` and
+ `Research/KernelCustomFirmwarePatches/` (one note per patch).
+ Kernel analysis and symbol lookups have their own procedure in
+ `Skills/kernel-analysis-vphone600/SKILL.md`; read it before touching them.
+- **Patch authoring:** `Skills/authoring-patch-sets/SKILL.md`.
+- **History:** `Research/History/` is a preserved snapshot; it can describe
+ scripts and variants that no longer exist.
+
+## Searching
+
+```sh
+grep -rn "PAM: initialisation" Research Documents # an exact error string
+grep -rln "bootstrap.install" Research Documents VPhoneDaemon
+git log --oneline --all -i --grep "roothide" | head -20 # why something changed
+```
+
+Search the exact error text first; the notes were written from real failures
+and quote them. Then search the RPC or file name. Issue numbers in notes
+(`#519`, `#520`) are GitHub issues in `Lakr233/vphone-cli`; `gh issue view 520`
+reads one.
+
+## Source layout
+
+| Question | Look in |
+| --- | --- |
+| What does a Launchpad CLI command do | `VPhoneLaunchpad/VPhoneLaunchpad/Control/VPhoneLaunchpadControlCommands.swift`; command table in `VPhoneLaunchpad/VPhoneLaunchpadShared/VPhoneLaunchpadControl.swift` |
+| What does `vphone.sock` accept | `VPhoneExecutable/VPhoneVirtualization/UI/VPhoneHostAutomationServer.swift` (header comment lists the verbs) |
+| An RPC method's parameters | `VPhoneDaemon/Daemon/GuestAPI.swift` and `GuestAPI+<Area>.swift` |
+| Bootstrap install | `VPhoneDaemon/Daemon/Bootstrap/GuestIrisinInstaller.swift` |
+| Creation steps | `VPhoneLaunchpad/VPhoneLaunchpad/Machines/VPhoneLaunchpadCreationPipeline.swift` |
+| Firmware patches | `VPhoneExecutable/VPhoneCommand/FirmwarePatcher/` |
+
+## When to stop and report
+
+Stop and tell the user, with the log path and the note you read, when:
+
+- the fix needs a host security change (SIP, boot-args, AMFI) or an
+ administrator password;
+- the note says the symptom is an open issue (check the "Open issues" sections);
+- the next step would destroy state: uninstalling a bootstrap, `cfw install`,
+ recreating a machine, removing a bundle;
+- the same fix has failed twice. A third blind attempt on a user's guest costs
+ more than a question.
+
+A new finding that is not in these docs belongs in a `Research/` note and the
+commit message, not in a scratch file.
diff --git a/Skills/vphone-guest-control/references/guest-layout.md b/Skills/vphone-guest-control/references/guest-layout.md
new file mode 100644
index 00000000..ed4654a9
--- /dev/null
+++ b/Skills/vphone-guest-control/references/guest-layout.md
@@ -0,0 +1,190 @@
+# Guest layout, ssh and the bootstrap
+
+A fresh guest has vphoned and the system changes the project ships, and
+nothing else: no package manager, no sshd, no shell tools. Everything in this
+file is about adding that environment (the "bootstrap") and then finding your
+way around it. Until it is installed, work only through `guest send` and
+`guest rpc`.
+
+## Contents
+
+- Two layouts: roothide and rootless
+- Installing the bootstrap
+- First package install
+- Inspecting and removing it
+- ssh: the shell is not in the real root
+- Handing a file to vphoned
+- Installing a `.deb`
+- What vphoned maintains for you
+
+## Two layouts: roothide and rootless
+
+| | roothide (recommended) | rootless (deprecated) |
+| --- | --- | --- |
+| Root of the environment | `/var/containers/Bundle/Application/.jbroot-<16 hex>` | `/var/jb`, a symlink to a physical directory under `/private/preboot` |
+| Default directory name | `.jbroot-000114514191980C` when none exists (the last byte is a checksum) | none |
+| Apps go in | `<jbroot>/Applications` | `/var/jb/Applications` |
+| Package `Architecture` | whatever the bootstrap's `dpkg --print-architecture` says; do not assume | `iphoneos-arm64` |
+| After installing an app | register it: `system.uicache` or `apps.refresh` | `uicache -p` in the postinst |
+
+The directory names `/var/jb` and `.jbroot-<hex>` are fixed by those two
+bootstraps. Always find the real root with `bootstrap.inspect`; do not
+hard-code it.
+
+```sh
+vphone-launchpad-cli guest rpc myphone bootstrap.inspect
+vphone-launchpad-cli guest rpc myphone device.info # see the layout fields below
+```
+
+`device.info` reports `jailbreak.layout` (`roothide`, `rootless`, `rootful` or
+`null`), `jailbreak.jbroot` and `jailbreak.source`. These key names belong to
+the host-guest protocol; read them as they are. Both null means there is no
+bootstrap yet (a read-only `/` is not evidence of a rootful one).
+
+Prefer **roothide** for new work. Rootless is kept for older setups.
+
+## Installing the bootstrap
+
+The bootstrap is the Irisin app plus the base directories and links a package
+manager needs. Two equivalent ways:
+
+- **In the VM window:** menu **Apps > Install Bootstrap…**, pick the layout in
+ the sheet. Holding Option shows **Install Bootstrap from File…** (a local
+ Irisin `.deb`). The item is enabled only when vphoned advertises
+ `bootstrap_install`.
+- **Over RPC:**
+
+ ```sh
+ vphone-launchpad-cli guest rpc myphone bootstrap.install '{"layout":"roothide"}'
+ vphone-launchpad-cli guest rpc myphone bootstrap.status
+ ```
+
+What `bootstrap.install` does, in order, and what to look at when a step fails:
+
+1. **preparing**: selects the layout. Refuses with an error if
+ `/private/var/db/vphoned/bootstrap.json` says a bootstrap is already
+ installed. (An uninstall writes a tombstone so this check is accurate.)
+2. **downloading**: fetches the latest `Lakr233/Irisin` release for the guest's
+ architecture and checks the GitHub SHA-256 digest and the Debian control
+ fields. The guest needs network. `bootstrap.status` reports
+ `downloaded_bytes` and `total_bytes` when the server gives a length.
+3. **extracting / installing**: unpacks the `.deb`, copies the payload into the
+ environment, creates Irisin's mobile-owned data directory, registers the app
+ and loads its daemon. No maintainer script runs.
+4. **firmware**: writes the `firmware` record (the guest iOS version) into the
+ environment's `Library/dpkg/status`, so Irisin's resolver sees it.
+5. **completed** or **failed** (with `error`). A launchd start error comes back
+ as `service_start_warning` while the install still stands; the daemon starts
+ on demand when Irisin opens, or after a reboot.
+
+For a local package: upload the `.deb` to exactly
+`/var/root/Library/Caches/vphoned-irisin-<UUID>.deb` (regular file, at most
+64 MiB, no symlinks) and pass it as `package_path`. vphoned validates name,
+architecture, version, executables and the launchd plist.
+
+For roothide, vphoned also builds what a bootstrap installer would: `tmp`,
+`var`, `etc`, the `dev` and `rootfs` links, copies of the passwd files, the
+user databases, and the `.jbroot` loader links. Do not recreate these by hand;
+they are repaired at every vphoned start.
+
+## First package install
+
+This step is done in the guest UI, in Irisin; there is no RPC for it.
+
+1. Open Irisin. Select **all** of `apt`, `bash`, `uikittools`, `launchctl`
+ and `openssh-server` at once.
+2. Press and hold the install button and choose **Bootstrap Install**.
+
+Install them together: they depend on each other, and `openssh-server` declares
+some dependencies circularly, so one-by-one installs can fail partway. After the
+first pass, install further packages normally. If the first pass fails, do not
+repair it in place: **Apps > Uninstall Bootstrap…**, then start over.
+
+Because this needs someone at the screen, drive it with `ui.tree`,
+`ui.tap_element` and screenshots, or ask the user to do it.
+
+## Inspecting and removing it
+
+```sh
+vphone-launchpad-cli guest rpc myphone bootstrap.inspect # every root found
+vphone-launchpad-cli guest rpc myphone bootstrap.uninstall '{"roots":["<path from inspect>"],"force":true}'
+```
+
+Uninstall removes **every listed root**, unloads their daemons, unregisters
+their apps, marks the record uninstalled and **reboots the guest** (add
+`"reboot":false` to skip). The paths must match the current inspection
+exactly. Irisin's data under `/var/mobile/Documents` is kept. It destroys the
+user's installed packages, so run it only when asked or as the stated recovery
+for a failed first install.
+
+## ssh: the shell is not in the real root
+
+ssh exists only after `openssh-server` is installed (see above); a fresh guest
+refuses port 22. `iproxy`, `idevice_id` and `ideviceinstaller` are third-party
+libimobiledevice tools; ask the user before installing them. Reach the guest
+through the host's usbmuxd with `iproxy`:
+
+```sh
+UDID=$(idevice_id -l | head -1) # or xcrun devicectl list devices: Reality "virtual"
+iproxy 2222 22 -u "$UDID" &
+ssh -p 2222 [email protected] # the credentials are not documented in the repo; ask the user
+```
+
+On roothide the session lands **inside the jbroot**, not the real root:
+
+- `/` in the shell is the environment's root. `/tmp`, `/var/mobile` and `/etc`
+ there are the bootstrap's copies, not the guest's.
+- The real filesystem is at **`/rootfs`**. `/rootfs/private/var/...` is the
+ guest's `/private/var/...`. Logs, app data and preferences are found there.
+- vphoned's `files.*`, `apps.*` and other RPCs use the **real** paths. A path
+ you see in the ssh shell is not valid for RPC until it is translated.
+- There is no `sudo` in a bare jbroot. Install `sudo` as a package first, log in
+ as root if the user has set that up, or do root work over RPC.
+
+Rule of thumb: when ssh and RPC disagree about whether a file exists, the
+difference is the `/rootfs` prefix.
+
+## Handing a file to vphoned
+
+To let an RPC (for example `apps.install`) read a file you put in through ssh:
+
+```sh
+scp -P 2222 App.ipa [email protected]:/tmp/App.ipa # lands in the jbroot's /tmp
+ssh -p 2222 [email protected] 'mv /tmp/App.ipa /rootfs/private/var/tmp/App.ipa'
+vphone-launchpad-cli guest rpc myphone apps.install '{"path":"/private/var/tmp/App.ipa"}'
+```
+
+Without ssh, use RPC only: `files.write` for small text. Binaries need the
+HTTP route `PUT /v1/files/content?path=<abs path>`, which exists only when the
+VM was launched with `vphone-cli vm launch --api-listen` outside `vm start`; ask
+the user rather than relaunching a running machine.
+
+## Installing a `.deb`
+
+With a bootstrap present, `dpkg` and `apt` work from an ssh shell as the
+environment's tools:
+
+```sh
+scp -P 2222 pkg.deb [email protected]:/tmp/
+ssh -p 2222 [email protected] 'sudo dpkg -i /tmp/pkg.deb' # needs sudo installed, or a root login
+```
+
+A package that ships an app must register it afterwards (`uicache -p` in the
+postinst for rootless, or `system.uicache` over RPC). Do not install a package
+over a half-built bootstrap.
+
+## What vphoned maintains for you
+
+You do not need to run these; knowing they exist explains odd behavior:
+
+- `.jbroot` loader links in every directory holding a Mach-O file, re-walked one
+ second after `Library/dpkg` changes. A `dyld ... @loader_path/.jbroot/...`
+ crash means a link is missing there.
+- sshd host keys and user databases, deferred until the packages exist, then
+ created within about a second of the next package operation or at the next
+ vphoned start.
+- The `firmware` record in `dpkg/status`, updated after an iOS version change.
+
+When something here misbehaves, read the notes listed in
+[finding-docs](finding-docs.md), especially `Research/Guest/roothide_bootstrap_base.md`
+and `Research/roothide_loader_links.md`.
diff --git a/Skills/vphone-guest-control/references/guest-socket.md b/Skills/vphone-guest-control/references/guest-socket.md
new file mode 100644
index 00000000..83f6607e
--- /dev/null
+++ b/Skills/vphone-guest-control/references/guest-socket.md
@@ -0,0 +1,82 @@
+# The machine socket: vphone.sock
+
+Every launch (headless too) serves `<library>/<name>/vphone.sock`, a Unix
+socket that takes one JSON object per connection and returns one JSON line.
+Connections are served concurrently. `vphone-launchpad-cli guest send` is the
+normal way to use it; for scripts `nc -U` works the same:
+
+```sh
+vphone-launchpad-cli guest send myphone '{"t":"ping"}'
+printf '%s\n' '{"t":"ping"}' | nc -U ~/.vphone/machines/myphone/vphone.sock
+```
+
+Use `controlSocket` from `vm list` as the path; it is null when the socket is
+not there yet.
+
+## Contents
+
+- Requests
+- Replies and the attached screen
+- Coordinates
+- Typing text
+- Patterns that work
+
+## Requests
+
+| Request | Does |
+| --- | --- |
+| `{"t":"ping"}` | Checks that vphoned answers |
+| `{"t":"screenshot","path":"/abs/shot.png"}` | Full-resolution capture to `path` (PNG or JPEG by extension). Without `path` it saves to the Desktop |
+| `{"t":"tap","x":645,"y":1398}` | Tap |
+| `{"t":"swipe","x1":645,"y1":2600,"x2":645,"y2":1400,"ms":300}` | Swipe; `ms` defaults to 300 |
+| `{"t":"key","name":"home"}` | `home`, `power`, `volup`, `voldown` are hardware HID keys. Any other name (`return`, `cmd+v`) goes to vphoned `input.key` |
+| `{"t":"type","text":"Hello"}` | Sets the **guest clipboard**; it does not type |
+| `{"t":"rpc","method":"<vphoned method>","params":{…}}` | Calls any vphoned method; see [rpc-methods](rpc-methods.md) |
+
+Unknown `t`, or missing fields, give `{"ok":false,"error":"…"}`.
+
+## Replies and the attached screen
+
+Success is `{"ok":true}`, with `result` for `rpc`, `path` for `screenshot`, and
+`image` when a screen is attached. Failure is `{"ok":false,"error":"…"}`.
+
+- `image` is a **small grayscale JPEG, base64**, meant for a quick "did
+ something change" glance. It is not the real screen. For anything you must
+ read (text, colors, layout), take a `screenshot` to a file and open the file,
+ or use `ui.describe` / `ui.ocr`.
+- `tap`, `swipe`, `key` and `type` attach one by default, 500 ms after the
+ action. Add `"screen":false` to skip it; add `"delay":<ms>` for slow
+ animations. `rpc` attaches none unless `"screen":true` (CLI: `guest rpc … --screen`).
+- Inputs on the socket are serialized by the host, so a quick series of
+ `tap` calls keeps its order. Wait for the reply before issuing the next.
+
+## Coordinates
+
+The socket's `tap` and `swipe` take **pixel coordinates of the 1290×2796
+screen** (origin top left). The vphoned methods `input.tap`, `input.swipe` and
+friends take **screen points**, as `device.screen` reports. Do not mix the two
+in one script. When you do not know where a control is, do not guess: call
+`ui.tree` or `ui.ocr`, which return positions, or use `ui.tap_element` with a
+text selector and skip coordinates entirely.
+
+## Typing text
+
+`{"t":"type"}` only fills the clipboard. Either follow it with a paste:
+
+```sh
+vphone-launchpad-cli guest send myphone '{"t":"type","text":"hello","screen":false}'
+vphone-launchpad-cli guest send myphone '{"t":"key","name":"cmd+v"}'
+```
+
+or call `input.type` through RPC, which sends key events (`delay_ms` between
+keys, default 30), or `input.paste`. Use `input.type` for short ASCII and
+paste for long or non-ASCII text.
+
+## Patterns that work
+
+- **Wake and unlock check:** `ping`, then `screenshot` to a file and look at it.
+- **Home:** `{"t":"key","name":"home"}`; **power** wakes or locks.
+- **Open an app without hunting for its icon:** `apps.launch` with the bundle id.
+- **Scroll a list:** swipe from lower to upper y, e.g. 2600 → 1400 at x 645.
+- **Retry on flaps:** `guest not connected` (shown as `客体代理未连接` in the
+ app) means the guest connection dropped mid-call. Wait a second and repeat; see [troubleshooting](troubleshooting.md).
diff --git a/Skills/vphone-guest-control/references/install-faq.md b/Skills/vphone-guest-control/references/install-faq.md
new file mode 100644
index 00000000..e931cb3e
--- /dev/null
+++ b/Skills/vphone-guest-control/references/install-faq.md
@@ -0,0 +1,102 @@
+# Install problems seen in issues
+
+These come from the repository's issue tracker (`Lakr233/vphone-cli`). Each
+entry gives the symptom the user reports, the cause, and the fix. Match on the
+symptom, apply the fix, and say which issue it was. Issue numbers are for
+`gh issue view <n>`.
+
+## Contents
+
+- Launchpad will not open, or Developer Tools access keeps switching off
+- Host checks fail
+- The host cannot run vphone at all
+- Bundle and Launchpad versions
+- Creating a machine
+- After the machine exists
+- Not an install problem
+
+## Launchpad will not open, or Developer Tools access keeps switching off
+
+**"vphone-launchpad is damaged and can't be opened"** (#527). The user
+downloaded a Launchpad zip that is not notarized. Releases 2.1.3 to 2.1.7 and
+2.2.1 are not notarized; the current list is in `Documents/Downloads/README.md`.
+Fix: download `vphone-launchpad-<version>-notarized.zip` for a notarized version
+of the **same series** as the bundle they want, and update the bundle to match
+(2.1.2 with bundle 2.1.5 was the answer in #527). A non-notarized zip can still
+be opened once via System Settings > Privacy & Security > **Open Anyway**, but
+see the next entry before recommending it.
+
+**Developer Tools access turns itself off again after the user enables it**
+(#540, also "Failed to get developer tools access" on macOS 27). Cause: macOS's
+privacy database still holds a Developer Tools entry for `com.vphone.launchpad`
+pinned to the code signature of an **earlier build**, typically an ad hoc
+signed copy from the plain zip or a self-build. On every launch the system
+compares that entry with the notarized app, sees a mismatch and revokes the
+grant. Flipping the switch changes only whether access is allowed, not the
+stale requirement. Fix:
+
+```sh
+tccutil reset DeveloperTool com.vphone.launchpad
+```
+
+then open Launchpad, choose **Open Settings**, turn the switch on for
+vphone-launchpad, and reopen Launchpad (the app does not close itself).
+Prevent a repeat by installing only the `-notarized` zip. Mixing the plain and
+the notarized zip, or a local build and a release, recreates the problem. A
+user on an ad hoc build must reset after every switch. `status` →
+`developerTools` shows the result.
+
+## Host checks fail
+
+| Symptom | Cause and fix |
+| --- | --- |
+| `csrutil: invalid command` for `allow-research-guests` (#226, also "does it work on Intel / hackintosh", #227, #253) | Check the spelling first (the #226 reporter typed `allow-research-agents`). If it is right, the Mac is not Apple silicon: there is no workaround, vphone needs an M-series Mac on macOS 15 or newer |
+| Host preflight says "This computer has several macOS installations … Pick a macOS installation" (#503, #511) | Dual-boot or an extra macOS volume. Fixed by PR #512; update Launchpad and the bundle within the series. Until then, the preflight cannot be satisfied from the app |
+| `vphone-vm` is killed before a window opens (#435 was a 1.x-era report of `zsh: killed`, closed as outdated; in 2.x `vphone-cli` is unentitled) | AMFI refused the entitled `vphone-vm`. `vphone-launchpad-cli bundle verify <version>` re-runs the allowlist. If SIP is on, the user needs the relaxation from `Documents/Guides/host-setup.md` (option B keeps SIP enabled with only debugging restrictions off). Do not suggest `csrutil disable` as a first step |
+| "Can I keep SIP on?" (#445) | Yes: `csrutil enable --without debug` plus `csrutil allow-research-guests enable` in Recovery; the allowlist tool ships in the bundle, no third-party tool needed |
+| `vphone-escalator` fails with `invalid address` reading the amfid singleton on macOS 27 (#506) | Seen on 2.0.8 with macOS 27.0 on a new chip; fixed by PR #518 in 2.1.0. Move to a newer series, then read `Research/Host/macos27_m6_amfi.md` |
+| `VZErrorDomain Code=6 … maximum supported number of active virtual machines has been reached` (#432) | macOS caps concurrent VMs (8 were running). Stop one. The limit is Apple's and is not something to bypass |
+
+## The host cannot run vphone at all
+
+- Running inside another macOS VM or Parallels (#166): not supported; the
+ guests need physical Apple silicon. EC2 Mac instances (#482) got no answer.
+- 1.x machines (#483, #495): VMs made by 1.x do not start in 2.x and there is no
+ in-place upgrade. Create a new machine. The 1.x tooling (Makefile, Python
+ scripts, amfidont) is gone; do not follow instructions written for it.
+
+## Bundle and Launchpad versions
+
+- Launchpad refuses a bundle that is too old; it may list bundles from a newer
+ series. Stay in the same series (`Documents/Downloads/README.md`).
+- Launchpad never updates itself; the user replaces the app.
+- A rebuilt local bundle needs `install-local` again (new signature).
+
+## Creating a machine
+
+| Symptom | Cause and fix |
+| --- | --- |
+| Every new machine downloads the IPSW again (#513) | Fixed in 2.0.9: remote IPSWs are cached once in `~/.vphone/ipsws`, GPU drivers per build in `~/.vphone/gpu-drivers/`. A leftover `.ipsw-cache/` inside an old machine can be deleted |
+| Creation with a 128 GB or 256 GB disk is slow or fails (#522), the disk shows a different size than requested (#523), firmware download is slow (#524) | All three are fixed since 2.1.1. On an older bundle, update within the series. Check free space before a large disk either way |
+| Creation fails at restore or first boot | [troubleshooting](troubleshooting.md) ("Creating a machine"), `vm log --kind create` |
+| `fw patch` crashes with SIGBUS (#466) | Fixed in the Capstone package that every 2.x release uses. On 2.1.0 or later it is a new bug: collect the version, the command and its output |
+
+## After the machine exists
+
+| Symptom | Cause and fix |
+| --- | --- |
+| Guest panics at launch ("Library not loaded: libSystem", no dyld cache) (#532) | The 2.1.6 `mis_trust_auth` patch broke the shared cache; fixed in c53733b, first released in 2.2.0. Update the bundle within the series and recreate the machine |
+| Guest panics at launch on a 27 base (#531) | The maintainer thought the first CFW install most likely did not finish (an inference). Running `cfw install` again on the stopped machine is a repair, not a routine step; do it only if the user asks |
+| Ethernet or location services missing (#521, #438) | The user chose the **experimental** preset. It is known to break things; recreate with `--preset standard`. (#536 also reported a host location-permission bug, since fixed; update the bundle within the series) |
+| iOS 18 machine stuck at the Apple logo after the first reboot, bundle newer than 2.1.0 (#541) | Open issue. Report it; do not recreate repeatedly. Bundle 2.1.0 booted that machine |
+| Irisin cannot install `openssh` (#528) | `launchctl` (and the other base packages) were missing. Install `apt`, `bash`, `uikittools`, `launchctl`, `openssh-server` together ([guest-layout](guest-layout.md)) |
+| ssh fails on roothide, `sudo` does not work (#502, #519, #520) | Missing bootstrap base items or loader links, fixed in later bundles. [guest-layout](guest-layout.md), `Research/Guest/roothide_bootstrap_base.md` |
+| A commercial app (WeChat, TikTok, games) crashes with `CODESIGNING Invalid Page` or is blocked by FairPlay (#212, #220, #356) | The project does not support specific third-party apps; those issues were closed as not planned. Say so, and do not try to patch around it. Apple's own and open-source apps are in scope |
+| An app is killed by `EXC_GUARD` (#291) | `Documents/Guides/troubleshooting.md` |
+
+## Not an install problem
+
+"Does Apple ID / App Store / iMessage work", "can I use the Mac's camera",
+"iPhone Duo", "passkeys" (#282, #326, #456, #481, #439): these are product
+questions. Read `Documents/Guides/compatibility.md` and the open issue, and
+say plainly that it is unsupported or unresolved rather than guessing.
diff --git a/Skills/vphone-guest-control/references/install.md b/Skills/vphone-guest-control/references/install.md
new file mode 100644
index 00000000..b6680f69
--- /dev/null
+++ b/Skills/vphone-guest-control/references/install.md
@@ -0,0 +1,128 @@
+# Installing vphone
+
+Read `status` first (`vphone-launchpad-cli status`) and skip every step it
+already shows as done. Steps 1 and 2 happen once per Mac, by the Mac's owner.
+
+## Contents
+
+- Host requirements
+- Launchpad
+- The CLI on PATH
+- VPhone.bundle and series matching
+- Testing a local build
+- When an install step fails
+- Checking the result
+
+## Host requirements
+
+- Apple Silicon, macOS 15 or newer. It does not run inside another VM, because
+ the guests need nested-free paravirtualization.
+- The entitled `vphone-vm` must be admitted by AMFI. The owner chooses one of
+ two host configurations in macOS Recovery (SIP off with
+ `amfi_get_out_of_my_way=1`, or SIP on `--without debug` plus an allowlist),
+ and both need `csrutil allow-research-guests enable`. The details are in
+ `Documents/Guides/host-setup.md` of the repository.
+- Launchpad's Host Setup page checks these, the network (`updates.cdn-apple.com`,
+ `api.github.com`), Developer Tools access and the root helper. When the
+ allowlist is the only thing missing, Launchpad applies it for you through its
+ helper, per bundle signature.
+
+Do not change SIP, boot-args or nvram yourself. They need a reboot into
+Recovery and are the owner's call. Say which check failed and stop.
+
+## Launchpad
+
+1. Open <https://github.com/Lakr233/vphone-cli/releases>.
+2. Download `vphone-launchpad-<version>-notarized.zip`. Use the plain
+ `vphone-launchpad-<version>.zip` only when the release has no notarized one;
+ macOS blocks it the first time, and the user must open System Settings >
+ Privacy & Security and click **Open Anyway**.
+3. Unzip and move the app to `/Applications`. Launchpad does not update itself:
+ to update, download the new version and replace the app.
+4. Open it once. On first launch the user completes Host Setup: allow
+ Developer Tools access, and install the helper (it asks for an administrator
+ password). Developer Tools access takes effect after Launchpad is relaunched.
+ `canInstallBundles` in `status` turns `true` when both are done.
+
+Which versions are notarized is listed in `Documents/Downloads/README.md`.
+
+## The CLI on PATH
+
+```sh
+mkdir -p ~/.local/bin
+ln -sf /Applications/vphone-launchpad.app/Contents/MacOS/vphone-launchpad-cli ~/.local/bin/
+vphone-launchpad-cli help
+```
+
+Do not use `sudo` for this; `~/.local/bin` must be on PATH, and calling the CLI by its full path works the same. The CLI starts Launchpad in the
+background if it is not running and waits for the control socket
+(`~/Library/Application Support/vphone-launchpad/control.sock`, mode 0600,
+same user only). Nothing listens on the network; reach it over ssh from another
+machine.
+
+## VPhone.bundle and series matching
+
+Launchpad and the bundle must share a **series**: the first two numbers of the
+version. Launchpad 2.2.3 works with any 2.2.x bundle, and the reverse. Patch
+releases inside a series stay interchangeable, so take the newest in the series.
+Launchpad refuses a bundle that is too old, but it may still list bundles from a
+newer series; do not install those, update Launchpad first.
+
+```sh
+vphone-launchpad-cli bundle install-release 2.2.3 # an explicit X.Y.z of Launchpad's series
+vphone-launchpad-cli bundle list
+vphone-launchpad-cli bundle use 2.2.3 # switch the active one
+vphone-launchpad-cli bundle verify 2.2.3 # re-check
+```
+
+`install-release` downloads the release from GitHub, verifies it, installs it
+into the root-owned store through the helper, makes it active, and runs host
+preflight. `bundle list` shows per version: `active`, `accepted`, `policy`,
+`preflight`, `preflightDetail`, `cdhashes`, `path`.
+
+Always pass an explicit version. `latest` means the newest release by publish
+date, prereleases included, and it is installed and made active at once, so it
+can land in a newer series than Launchpad. Read Launchpad's version with
+`/usr/libexec/PlistBuddy -c 'Print CFBundleShortVersionString' /Applications/vphone-launchpad.app/Contents/Info.plist`
+(`status` does not report it), then pick the newest non-prerelease `X.Y.z` of the
+same `X.Y` from `gh release list -R Lakr233/vphone-cli` or the releases page.
+
+`bundle accept <version>` uses a version although its checks failed and
+`--off` takes that back. `bundle remove <version>` deletes one. Neither is for
+routine use; ask first.
+
+The first step that needs the helper after its five-minute authorization
+expires asks the user for an administrator password on the Mac. Warn them
+before running one, and do not retry in a loop while a prompt is open.
+
+## Testing a local build
+
+From a source checkout:
+
+```sh
+xcodebuild -workspace VPhone.xcworkspace -scheme VPhone \
+ -configuration Debug -destination 'platform=macOS,arch=arm64' \
+ -derivedDataPath .build/XcodeBundle build
+
+vphone-launchpad-cli bundle install-local .build/XcodeBundle/Build/Products/Debug/VPhone.bundle
+```
+
+`install-local` takes a folder or a `.zip`, installs it as `<version>-local`,
+makes it active, adds the execution policy exception, allows the new
+`vphone-vm` cdhash and runs preflight. Relative paths are resolved by the CLI.
+Every rebuild changes the cdhash, so run `install-local` again (or
+`bundle verify <version>-local`) after each build. Compare against the release
+it replaces with `bundle use <version>`.
+
+## When an install step fails
+
+Match the symptom in [install-faq](install-faq.md) before trying anything:
+"damaged and can't be opened", Developer Tools access switching itself off
+(`tccutil reset DeveloperTool com.vphone.launchpad`), several macOS
+installations, `zsh: killed`, and the rest.
+
+## Checking the result
+
+`vphone-launchpad-cli status` should show `hostReady: true`, `helper` as
+`ready (…)`, `bundleReady: true` and an `activeBundle`. Then continue with
+[machines](machines.md).
diff --git a/Skills/vphone-guest-control/references/machines.md b/Skills/vphone-guest-control/references/machines.md
new file mode 100644
index 00000000..b46aa881
--- /dev/null
+++ b/Skills/vphone-guest-control/references/machines.md
@@ -0,0 +1,129 @@
+# Machines: create, run, update
+
+## Contents
+
+- Inspect
+- Create
+- Retry a failed creation
+- Start, wait, stop
+- Logs
+- Updating a machine's guest components
+- Where things live
+
+## Inspect
+
+```sh
+vphone-launchpad-cli vm list
+```
+
+One object per machine: `name`, `libraryRoot`, `state` (`stopped`, `running`,
+`busy: <activity>`), `cpuCount`, `memoryMB`, `network`, `panicked`, `log`,
+`controlSocket` (null until the machine serves `vphone.sock`), and when known
+`udid`, `ios` and `cloudOS`. Check `state` before any machine command; start
+and update refuse a machine that is not `stopped`.
+
+## Create
+
+A creation downloads two IPSWs, patches the boot chain, restores through DFU,
+installs the custom firmware into the guest, and boots once to prove vphoned
+answers. It leaves a **stopped** machine. Success is not a running guest.
+
+Before starting, check free disk (tens of GB, more with `--keep-artifacts`),
+that no other creation is running, and that `status` shows `bundleReady`.
+
+```sh
+vphone-launchpad-cli vm create myphone \
+ [--iphone-source <path-or-url>] [--cloudos-source <path-or-url>] \
+ [--cpu 8] [--memory 8192] [--disk-size 64] \
+ [--network nat|bridged|none] [--preset standard|experimental] \
+ [--keep-artifacts] [--no-wait]
+```
+
+- **Sources are optional.** If either is omitted, the newest pairing from
+ `vphone-cli fw catalog` is used (the CLI prints `firmware: <iphone> + <cloudos>`).
+ Pass both explicitly to pin a pairing; verified pairings are listed in
+ `Documents/Guides/compatibility.md`. Local paths are read in place; URLs are
+ cached in `~/.vphone/ipsws/`.
+- **Units:** `--cpu` is a count, `--memory` is **MB**, `--disk-size` is **GB**.
+ Defaults 8, 8192, 64. All must be positive integers.
+- **Name:** letters, digits, `.`, `-`, `_`. Keep it short: the machine path must
+ fit a Unix socket path, and the command says so if it does not.
+- **`--preset`** picks the patch preset: `standard` (default) or `experimental`.
+- **`--no-wait`** returns at once with a report instead of streaming the
+ pipeline. Without it the CLI streams the creation log and returns when the
+ pipeline stops.
+- The nine steps, in order: `create`, `prepare`, `patch`, `bootDFU`, `waitDFU`,
+ `restore`, `stopDFU`, `installCFW`, `firstBoot`. The final JSON report lists
+ each with `status` and `seconds`, plus the `log` path.
+- Creation needs network access for the restore ticket. Do not interrupt a
+ restore by killing processes; the window owns it.
+
+If the name exists or a creation under it is running, the command refuses.
+Choose a new name rather than reusing a half-built machine.
+
+## Retry a failed creation
+
+```sh
+vphone-launchpad-cli vm create myphone --from restore
+```
+
+`--from` takes one of the step names above and reruns from there. It works only
+for a creation **this running Launchpad has started since it launched**; after a
+relaunch it says there is nothing to retry. In that case create under a new
+name. Read why it failed first:
+
+```sh
+vphone-launchpad-cli vm log myphone --kind create --lines 200 # create | dfu | patch
+```
+
+## Start, wait, stop
+
+```sh
+vphone-launchpad-cli vm start myphone --wait [--timeout 300]
+vphone-launchpad-cli vm start myphone --headless --wait
+vphone-launchpad-cli vm wait myphone --timeout 300
+vphone-launchpad-cli vm stop myphone
+```
+
+- `--wait` pings vphoned over `vphone.sock` every second until it answers. It
+ fails early, with the console log path, on a kernel panic or when the VM
+ process exits. The default timeout is 300 s, which first boots can use up.
+- A window opens by default. `--headless` runs without one, and the guest is
+ driven entirely through `vphone.sock`.
+- `vm start` refuses a machine that is running or busy. If the VM was started
+ elsewhere, use `vm wait`.
+
+## Logs
+
+```sh
+vphone-launchpad-cli vm log myphone --lines 100
+vphone-launchpad-cli vm log myphone --kind create|dfu|patch --lines 200
+```
+
+Files live in `~/Library/Logs/vphone-launchpad/`: `<name>.log` (VM console and
+kernel output), `<name>-create.log`, `<name>-dfu.log`, `<name>-patch.log`.
+
+## Updating a machine's guest components
+
+For a **stopped** machine:
+
+```sh
+vphone-launchpad-cli cfw update-environment myphone
+```
+
+This redeploys the active bundle's guest resources (vphoned and the hook
+dylibs) and changes nothing else. Do it after moving to another bundle version.
+`cfw install myphone` redoes the whole custom-firmware install through the root
+helper; use it only to repair a machine, and only when asked.
+
+## Where things live
+
+| Path | Contents |
+| --- | --- |
+| `~/.vphone/machines/<name>/` | One machine: disk, `config.plist`, `vphone.sock` while running |
+| `~/.vphone/ipsws/` | Downloaded source IPSWs, shared |
+| `~/.vphone/gpu-drivers/<version>_<build>/` | GPU driver extracted per cloudOS build, shared |
+| `~/Library/Logs/vphone-launchpad/` | Console and creation logs |
+
+`VPHONE_ROOT` relocates the library and caches. Launchpad can hold several
+libraries; `status.libraries` lists them.
diff --git a/Skills/vphone-guest-control/references/rpc-methods.md b/Skills/vphone-guest-control/references/rpc-methods.md
new file mode 100644
index 00000000..d73885af
--- /dev/null
+++ b/Skills/vphone-guest-control/references/rpc-methods.md
@@ -0,0 +1,203 @@
+# vphoned methods
+
+`guest rpc <machine> <method> '<params-json>'` calls a method in the guest's
+daemon, through the machine's `vphone.sock`. Params are one JSON object (omit
+for none). The reply is `{"ok":true,"result":{…}}`. On `ok:false` the CLI exits 1 with
+"The machine refused the request. Try again." and puts the guest's own error
+(for example `guest not connected` or `Unknown method: …`) on stderr;
+add `--screen` to also get the small grayscale screen image.
+
+The complete catalog, with REST routes and result details, is
+`Research/vphoned_http_api.md` ("Method catalog"). This file is the working
+subset with parameter names checked against the daemon source
+(`VPhoneDaemon/Daemon/GuestAPI*.swift`). When a call fails with an
+invalid-request error, read the source named there instead of guessing keys.
+
+## Contents
+
+- Conventions
+- Device and screen
+- Input
+- UI inspection
+- Apps
+- Installing an app
+- Files
+- Processes, logs, services
+- System and preferences
+- Bootstrap
+- Raw HTTP and WebSocket
+
+## Conventions
+
+- Coordinates for `input.*` and `ui.element_at` are **screen points** as
+ `device.screen` reports, not the pixels used by the socket's `tap`.
+- **force methods** refuse to run unless the params carry `"force":true`:
+ `processes.kill`, `services.stop|disable|remove|signal|unload`,
+ `apps.uninstall|unregister|unregister_dir`, `system.respring`,
+ `system.reboot`, `setup.skip`. The flag is the confirmation: use it only for
+ what the user asked.
+- Results can be large. Methods that read data take `limit`, `max_lines`,
+ `max_elements` or a `filter`; use them. A reply in the 8–16 KiB band can be
+ lost on close (see [troubleshooting](troubleshooting.md)).
+- Capability flags in `/v1/health` tell which areas this vphoned supports. An
+ `unknown method` error against an older guest means update its environment
+ ([machines](machines.md)).
+
+## Device and screen
+
+| Method | Params | Notes |
+| --- | --- | --- |
+| `device.info` | none | Snapshot plus network, screen, rotation, brightness, volume, low power, Developer Mode. Start here |
+| `device.snapshot`, `device.screen`, `device.network` | none | Smaller views of the same |
+| `screen.screenshot` | none | Base64 JPEG with `mime_type`, `width`, `height` (1290×2796) |
+| `display.brightness`, `audio.volume` | `value?` | Omit `value` to read |
+| `display.rotation`, `display.orientation` | `orientation?` | |
+| `device.ioreg` | `plane` | e.g. `IODeviceTree` |
+
+## Input
+
+| Method | Params |
+| --- | --- |
+| `input.tap` | `x`, `y` |
+| `input.double_tap` | `x`, `y`, `interval?` (0.1) |
+| `input.long_press` | `x`, `y`, `seconds?` (1) |
+| `input.swipe` | `x1`, `y1`, `x2`, `y2`, `seconds?` (0.3), `steps?` (20) |
+| `input.drag` | `points` (≥2 `[x,y]` pairs), `seconds?`, `hold?`, `steps?` |
+| `input.touch_sequence` | `events` (`{phase,x,y,delay_ms}`), `normalized?` (true) |
+| `input.button` | `name` (hardware button) |
+| `input.key` | `name` (`return`, `cmd+v`, …) |
+| `input.type` | `text`, `delay_ms?` (30) |
+| `input.paste` | `text` |
+
+## UI inspection
+
+Prefer these to coordinates.
+
+| Method | Params | Notes |
+| --- | --- | --- |
+| `ui.describe` | none | Short description of the screen; cheapest orientation |
+| `ui.tree` | `max_elements?` (500), `visible_only?` (true), `clickable_only?`, `limit?` | Accessibility elements with positions |
+| `ui.element_at` | `x`, `y` | |
+| `ui.tap_element` | selector | Taps the match |
+| `ui.wait`, `ui.wait_gone` | selector, `timeout?` (10 s) | Wait for an element to appear or go |
+| `ui.ocr` | `languages?` (`["en-US"]`), `min_confidence?` (0.3) | Text with boxes; use for non-accessible UI |
+
+Selector keys: `text`, `identifier`, `role`, `match` (`contains` by default),
+`index` (0). Example:
+`ui.tap_element '{"text":"General","match":"contains"}'`.
+
+## Apps
+
+| Method | Params |
+| --- | --- |
+| `apps.list` | `filter?` (`all` default) |
+| `apps.search` | `query` |
+| `apps.launch` | `bundle_id`, `url?`. Returns `pid` and `frontmost_verified` |
+| `apps.foreground` | none; reports the verified front app |
+| `apps.terminate` | `bundle_id` |
+| `apps.open_url` | `url`, `bundle_id?` |
+| `apps.info`, `apps.binary`, `apps.data_dir` | `bundle_id` |
+| `apps.refresh` | `directory?`; same as `system.uicache` for registration |
+| `apps.register`, `apps.registration` | `path` |
+| `apps.uninstall` (force) | `bundle_id` |
+
+`frontmost_verified:false` on a launch means the process started but no unique
+foreground app could be confirmed. Check with a screenshot.
+
+## Installing an app
+
+Never `xcrun devicectl`: it times out against these guests. Two routes with
+different meaning:
+
+- **Through installd** (what Xcode does, and the only route that exercises the
+ install gate): `ideviceinstaller -u <UDID> install App.ipa`. The UDID comes
+ from `idevice_id -l` or `vm list`.
+- **Through vphoned:** `apps.install '{"path":"/private/var/tmp/App.ipa"}'`,
+ optional `registration:"System"` and `cert_path`. `path` is a **guest** path,
+ and vphoned **deletes the file after installing**. It re-signs and places the
+ bundle itself, bypassing installd and the profile checks, and keeps the app's
+ own entitlements (so `get-task-allow` survives, which is the way to get a
+ debuggable test app in). It proves nothing about installd. To get the file
+ into the guest, see [guest-layout](guest-layout.md) ("Handing a file to
+ vphoned").
+
+Then launch with `apps.launch`.
+
+## Files
+
+Paths are real-root paths. All take `path` unless noted.
+
+| Method | Params |
+| --- | --- |
+| `files.list` | `path` |
+| `files.read` | `path`, `limit?`, `binary?` (base64) |
+| `files.write` | `path`, `content`, `encoding?` (`utf8`) |
+| `files.mkdir` | `path` |
+| `files.remove` | `path`, `recursive?` |
+| `files.rename` | `from`, `to` |
+| `files.copy` | `from`, `to` |
+| `files.find` | `root`, `pattern` |
+| `files.symlink` | `target`, `link`, `replace?` |
+| `files.chmod` | `path`, `mode` |
+| `files.chown` | `path`, `owner` |
+| `files.plist` | `path` |
+| `files.plist_set` | `path`, `key`, and `value` or `remove:true` |
+
+Use `files.read` with `binary:true` to pull guest binaries and crash reports
+without ssh. Keep `limit` small; large reads are the usual way to hit the reply
+size problem.
+
+## Processes, logs, services
+
+| Method | Params | Notes |
+| --- | --- | --- |
+| `processes.list` | `filter?` | `cpu_seconds`, `start_time`, footprint, jetsam band; a stuck SpringBoard shows ~0 CPU |
+| `processes.kill` (force) | `pid`, `signal?` | |
+| `memory.jetsam`, `memory.pressure` | none | |
+| `logs.syslog` | `seconds?` (2, max 60), `process?`, `level?` (`all`), `max_lines?` (500) | A bounded capture |
+| `logs.crashes` | `bundle_id?` | Lists reports: `path`, `process`, `size`, `mtime` |
+| `logs.crash` | `path` | Reads one report |
+| `services.list` | none | launchd |
+| `services.status`, `services.print` | `label` | |
+| `services.start`, `services.enable` | `label` | |
+| `services.stop`, `disable`, `remove`, `unload` (force) | `label` | |
+| `launchd.getenv` / `setenv` / `unsetenv` | `key`, `value?` | |
+
+## System and preferences
+
+| Method | Params |
+| --- | --- |
+| `system.uicache` | none; re-registers apps |
+| `system.respring` (force), `system.reboot` (force) | `userspace?` for reboot |
+| `setup.status` | none; `setup.skip` (force) skips Setup Assistant |
+| `developer_mode.status` / `enable` | none |
+| `settings.get` | `domain`, `key?` |
+| `settings.set` | `domain`, `key`, `value`, `type?` |
+| `settings.delete` | `domain`, `key` |
+| `clipboard.get` / `set` / `clear` | `set` takes `text` |
+| `location.set` / `clear` / `current` | `set` takes latitude/longitude; read-back can fail on some guests |
+| `notify.post` / `notify.state` | `name`, `state?` |
+| `keychain.*` | Lists, adds and edits secrets; use only on request and never print values |
+
+## Bootstrap
+
+`bootstrap.install {layout, package_path?}`, `bootstrap.status`,
+`bootstrap.inspect`, `bootstrap.uninstall {roots, force, reboot?}`,
+`bootstrap.firmware`. Behavior and the install flow: [guest-layout](guest-layout.md).
+
+## Raw HTTP and WebSocket
+
+The same methods are served as HTTP/WebSocket on guest VSOCK 1339. A host
+listener exists only if the VM was launched with `vphone-cli vm launch
+--api-listen host:port` (the launch prints `[api] token: …`); `vm start` has no
+such option, so an agent cannot enable it through the CLI. Use it on loopback only:
+
+```sh
+curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+ -d '{"method":"device.snapshot","params":{}}' http://127.0.0.1:8765/v1/rpc
+```
+
+It adds streaming file transfer (`GET/PUT /v1/files/content?path=`), a TCP
+tunnel to a guest port (`/v1/ports/<port>` over WebSocket) and an event stream
+(`/v1/events`). Every `POST` needs `Content-Type: application/json`. Details
+and the 401/403/415 rules: `Research/vphoned_http_api.md` ("Access control").
diff --git a/Skills/vphone-guest-control/references/troubleshooting.md b/Skills/vphone-guest-control/references/troubleshooting.md
new file mode 100644
index 00000000..889f0faf
--- /dev/null
+++ b/Skills/vphone-guest-control/references/troubleshooting.md
@@ -0,0 +1,104 @@
+# Troubleshooting
+
+Work from the symptom to the first thing worth checking. Each entry says what
+to read, so the fix comes from evidence on the user's own guest. For deeper
+background, [finding-docs](finding-docs.md) maps symptoms to the repository's
+notes.
+
+## Contents
+
+- Setup and host
+- Creating a machine
+- Starting a machine
+- Talking to the guest
+- Black screen
+- Apps and the bootstrap
+- Reporting
+
+## Setup and host
+
+| Symptom | Cause and what to do |
+| --- | --- |
+| `vphone-launchpad-cli: command not found` | Not installed or not on PATH. [install](install.md) |
+| `canInstallBundles: false` | `helper` is missing or outdated, or Developer Tools access is not granted. The user fixes it in Launchpad's Host Setup; relaunch Launchpad afterwards |
+| "The active VPhone.bundle has not passed its checks" | `bundle verify <version>`. If it keeps failing, read `bundle list` → `preflightDetail` |
+| `vphone-vm` is killed before a window opens | AMFI refused the entitled binary. `bundle verify`; a rebuilt bundle has a new cdhash and needs the allowlist again. Host SIP/AMFI settings are the owner's to change |
+| Prompt for an administrator password | Expected after the helper's five-minute authorization lapses. Tell the user; do not loop |
+| Launchpad too old for the bundle | Series mismatch. Update Launchpad; do not install a newer-series bundle |
+
+## Creating a machine
+
+- Read the failing step from the report (`steps[].status`) and then
+ `vm log <name> --kind create --lines 200` (also `dfu`, `patch`).
+- Retry from the step with `--from <step>` only if this Launchpad run started
+ the creation. Otherwise create again under a **new** name.
+- Out of disk shows up late and confusingly. Check free space before retrying.
+- The first-boot check waits up to 300 s. A guest that boots but never answers
+ is a vphoned problem; look at the console log.
+- Do not run two creations at once.
+
+## Starting a machine
+
+| Symptom | Check |
+| --- | --- |
+| "already running or busy" | `vm list`; wait for the activity, or `vm stop` |
+| `--wait` times out | `vm log <name> --lines 200`; look for a panic line. First boots can exceed 300 s; retry with `--timeout 900` before concluding |
+| "had a kernel panic" | The log path is in the error. Report it; do not retry blindly |
+| "stopped before vphoned answered" | The VM process exited; read the console log tail |
+| `controlSocket` is null | The machine is not serving its socket yet |
+
+## Talking to the guest
+
+- **`guest not connected`** (the app shows `客体代理未连接`) in the middle of a call.
+ Through the CLI this is exit 1 with the detail on stderr:
+ the guest connection flapped. Retry after a second, up to a handful of
+ times. If it persists while vphoned's PID has not changed, suspect the reply
+ size: vsock close drops replies of roughly 8–16 KiB. Re-ask with `limit`,
+ `max_lines`, `max_elements` or a narrower `filter`.
+- **`unknown method`:** the guest's vphoned is older than the bundle. Stop the
+ machine and run `cfw update-environment <name>`.
+- **`ok` but nothing changed on screen:** inputs are asynchronous; wait for the
+ attached `image` or take a screenshot. A locked or asleep screen swallows
+ taps: press `power`, then `home`.
+- **Taps land in the wrong place:** the socket takes pixels (1290×2796); the
+ `input.*` RPCs take points. Use `ui.tree` / `ui.tap_element` instead.
+- **Port 22 refused over iproxy:** no sshd yet. Use RPC; see
+ [guest-layout](guest-layout.md).
+
+## Black screen
+
+SpringBoard alive but the screen stays black (near-zero CPU) means data
+migration is hung, not that the display is broken.
+
+1. `processes.list` with `{"filter":"SpringBoard"}`: check `cpu_seconds` and
+ `start_time` for a stuck process.
+2. `logs.crashes {}` and look for `stacks+com.apple.datamigrator-*.ips`. Read it
+ with `logs.crash {"path":…}`; its `reason` names the plugin, and the
+ stackshot's `turnstileInfo` chain shows what it is waiting on.
+3. If the chain ends in a crashing system daemon, pull that binary with
+ `files.read {"path":…, "binary":true, "limit":…}` and read its crash report.
+ One known cause was a daemon crash-looping on a hypervisor-presence check.
+4. Read `Research/Patches/hv_vmm_present_usermode_xrefs.md` and
+ `Documents/Guides/troubleshooting.md`, then report. Do not recreate the
+ machine to test a theory.
+
+## Apps and the bootstrap
+
+- **"Press home to continue" lock screen:** `{"t":"key","name":"home"}`.
+- **App crashes with `EXC_GUARD` / Mach port guard:** a known kernel-patch
+ scope limit on 26.x bases; see `Documents/Guides/troubleshooting.md`.
+- **`dyld ... @loader_path/.jbroot/...` crash** after installing a package:
+ a loader link is missing. vphoned re-links within about a second of a package
+ operation; touch `Library/dpkg` or wait, then relaunch. See
+ `Research/roothide_loader_links.md`.
+- **First bootstrap package install fails:** do not patch it in place;
+ uninstall the bootstrap and start again ([guest-layout](guest-layout.md)).
+- **Irisin "Starting…" forever, `id root` fails, sshd resets connections:**
+ roothide base items are missing; `Research/Guest/roothide_bootstrap_base.md`.
+- **App installed with `apps.install` does not appear:** `system.uicache`.
+
+## Reporting
+
+When you stop, give the user: what you ran, the exact error (stderr), the log
+file path, the note you read, and the one decision you need from them. Keep it
+to what you observed; do not claim a cause you did not verify.