Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Rebuild the manual in four languages and serve research notes on the site

Lakr233a5faa7565c7d
diff --git a/.github/workflows/website.yml b/.github/workflows/website.yml
index 7d3df62c..777d696a 100644
--- a/.github/workflows/website.yml
+++ b/.github/workflows/website.yml
@@ -1,6 +1,6 @@
name: website
-# Builds the documentation site from Documents/ and README.md with Rspress
+# Builds the documentation site from Documents/ and Research/ with Rspress
# (VPhoneWebsite/) and publishes it to GitHub Pages from main.
on:
@@ -8,13 +8,13 @@ on:
branches: [main]
paths:
- Documents/**
- - README.md
+ - Research/**
- VPhoneWebsite/**
- .github/workflows/website.yml
pull_request:
paths:
- Documents/**
- - README.md
+ - Research/**
- VPhoneWebsite/**
- .github/workflows/website.yml
workflow_dispatch:
diff --git a/AGENTS.md b/AGENTS.md
index bfd3fbbf..b3dbe7b1 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -8,9 +8,9 @@ Virtual iPhone boot tool using Apple's Virtualization.framework with PCC researc
- **Test:** Run the Xcode test schemes in their owning projects. The `VPhone` build validates the finished bundle.
- **Boot (GUI):** `vphone-cli vm launch <name>`
- **Boot (DFU):** `vphone-cli vm launch <name> --dfu`
-- **AMFI refuses `vphone-vm`?** Launchpad uses its SMJobBless helper to run the installed bundle's `vphone-escalator` after checking its receipt. Standalone CLI users can run the allowlist tool as shown in `Documents/Guides/host-setup.md`. Repeat after the VM cdhash changes.
+- **AMFI refuses `vphone-vm`?** Launchpad uses its SMJobBless helper to run the installed bundle's `vphone-escalator` after checking its receipt. Standalone CLI users can run the allowlist tool as shown in `Documents/en/get-started/host-setup.md`. Repeat after the VM cdhash changes.
- **Restore:** `vphone-cli restore` runs in process over the vendored recovery and restore C modules in `VPhoneExecutable/VPhoneCommand/VPhoneRestore`.
-- **Platform:** macOS 15+ (Sequoia). `vphone-vm` needs amfid to accept its private entitlements: either SIP off with `amfi_get_out_of_my_way=1`, or SIP on (`--without debug`) plus an allowlist bypass. Both are in `Documents/Guides/host-setup.md`. Launchpad's bundle preflight checks SIP and Research Guests and applies the allowlist through its installed helper.
+- **Platform:** macOS 15+ (Sequoia). `vphone-vm` needs amfid to accept its private entitlements: either SIP off with `amfi_get_out_of_my_way=1`, or SIP on (`--without debug`) plus an allowlist bypass. Both are in `Documents/en/get-started/host-setup.md`. Launchpad's bundle preflight checks SIP and Research Guests and applies the allowlist through its installed helper.
- **Language:** Swift 6.0 in handwritten Xcode projects, private APIs via [Dynamic](https://github.com/mhdhejazi/Dynamic).
- **Dependencies:** Host and guest SwiftPM packages resolve dependencies by URL and version; `Package.resolved` pins the full graphs. There are no git submodules. **No Python anywhere, and no Homebrew package at runtime** — see Tiers below.
- **Installing an app on a guest: not `devicectl`.** `xcrun devicectl device install app` / `process launch` time out against vphone guests; do not use them. To go through installd (the path Xcode takes, and the only one that exercises the install-gate hooks), use `ideviceinstaller -u <UDID> install <ipa>`. vphoned's `apps.install` bypasses installd — it re-signs and places the bundle itself — so it proves nothing about installd. Launch with the `apps.launch` RPC.
@@ -50,8 +50,8 @@ See `Research/` for detailed firmware pipeline, component origins, patch breakdo
- `VPhoneKit`: shared core, archive, and external access kits with their tests.
- `VPhoneDaemon`: guest `vphoned`, native operations, and daemon configuration.
- `VPhoneGuestComponents`: guest dylibs built by Makefile from the bundle build phase.
-- `VPhoneWebsite`: the documentation site (Rspress, Node at build time only). `scripts/sync-docs.mjs` generates its pages from `README.md`, `Documents/` and the section tables of `Documents/README.md`, which also make the sidebar; `Documents/` stays the only source. `.github/workflows/website.yml` builds it and deploys GitHub Pages from main.
-- `VPhoneLaunchpad`: `vphone-launchpad.app`, the workstation app that downloads and manages `VPhone.bundle` releases and drives each VM through the `vphone-cli` of the Core Bundle that machine is bound to (`launchpad.json` in the machine folder; the default bundle only seeds new machines and library-wide commands), plus its SMJobBless helper `com.vphone.launchpad.helper`, `vphone-launchpad-cli`, a stateless client of the running app over a same-user Unix socket (`Documents/Guides/launchpad-cli.md`; use it to install and test a local `VPhone.bundle` build), and `vphone-launchpad-launcher`, the responsible process for each VM it starts. Shipped separately from the bundle. Settings live only in `VPhoneLaunchpad/Configuration/*.xcconfig`; the pbxproj holds none.
+- `VPhoneWebsite`: the documentation site at https://lakr233.github.io/vphone-cli/ (Rspress, Node at build time only). `scripts/sync-docs.mjs` generates it from the repository: the user manual in `Documents/<lang>/` (`en`, `zh`, `ja`, `ko`; one identical tree per language, English is the source, the section tables of each `Documents/<lang>/README.md` are its sidebar) and the research notes in `Research/`, served untranslated under `/research/`. A manual page added or changed in English needs the same change in every translation, and the translations pass the global Argon review before they ship. The root `README.md` stays short (header, screenshot, agent install prompt, acknowledgements, license) and points to the site. `.github/workflows/website.yml` builds it and deploys GitHub Pages from main.
+- `VPhoneLaunchpad`: `vphone-launchpad.app`, the workstation app that downloads and manages `VPhone.bundle` releases and drives each VM through the `vphone-cli` of the Core Bundle that machine is bound to (`launchpad.json` in the machine folder; the default bundle only seeds new machines and library-wide commands), plus its SMJobBless helper `com.vphone.launchpad.helper`, `vphone-launchpad-cli`, a stateless client of the running app over a same-user Unix socket (`Documents/en/launchpad/launchpad-cli.md`; use it to install and test a local `VPhone.bundle` build), and `vphone-launchpad-launcher`, the responsible process for each VM it starts. Shipped separately from the bundle. Settings live only in `VPhoneLaunchpad/Configuration/*.xcconfig`; the pbxproj holds none.
The `VPhone` scheme puts host programs in `VPhone.bundle/Contents/MacOS` and everything installed into the guest (vphoned, guest dylibs, their plists) in `Contents/Resources/guest-resources`. Xcode targets have `CODE_SIGNING_ALLOWED=NO`; the bundle build phase signs each binary ad hoc with only its own entitlements, then seals the outer bundle. `VPhoneVirtualization.entitlements` belongs to `vphone-vm`; `VPhoneDaemon.entitlements` belongs to `vphoned`. The bundle and CLI have no private entitlements.
@@ -63,7 +63,7 @@ The `VPhone` scheme puts host programs in `VPhone.bundle/Contents/MacOS` and eve
- `vphone-cli` is the unentitled entry point. `VPhoneGuestLaunchPlanner` resolves `vphone-vm` beside the running executable, checks its entitlements, probes AMFI, and reports the exact allowlist command on refusal. It never obtains root itself.
- `vphone-escalator` manages AMFI cdhash admission only. It writes amfid heap state, not executable code. Root authorization belongs to the user or to `vphone-launchpad`; neither `vphone-cli` nor the bundle has an SMJobBless or sudo password flow.
- `vphone-launchpad` has no private entitlements. `SignLaunchpad.sh` gives its main executable two hardened-runtime resource entitlements, microphone (`com.apple.security.device.audio-input`) and location (`com.apple.security.personal-information.location`), from `VPhoneLaunchpad/Resources/VPhoneLaunchpad.entitlements`; its helper, CLI and launcher have none. It asks for Developer Tools access (`EPDeveloperTool`) and adds an `EPExecutionPolicy` exception for each installed bundle. `EPDeveloperTool.authorizationStatus` keeps the value the process launched with, while syspolicyd checks the live grant on every exception request, so Host Setup judges access by asking for an exception for Launchpad's own executable; a grant or a revocation in Settings applies without a relaunch. Its helper is the only root surface: it installs verified releases into the root-owned store `/Library/Application Support/vphone-launchpad/Bundles`, runs that bundle's `vphone-escalator allow` for its receipt-pinned `vphone-vm`, runs `cfw install` from that store after rechecking the recorded cdhash, and runs that store bundle's `vphone-cli vm leases --release-orphans` for the caller's own library folders. There is no generic command verb. Launchpad starts `vm launch` detached (own session, responsibility disclaimed) through `vphone-launchpad-launcher` in its `Contents/MacOS`, which starts `vphone-cli` as an ordinary child and stays until it exits, forwarding stop signals and exiting the same way. The launcher is therefore the responsible process for `vphone-vm`. As a tool in the app's `Contents/MacOS` it is attributed to the app, so privacy prompts, usage descriptions and grants (microphone, location) are the app's, asked once for its Developer ID signature instead of for each ad hoc signed bundle build; under the hardened runtime macOS refuses them without asking unless the app carries the matching entitlement. It refuses anything but `vm launch` of a `vphone-cli` in the root-owned store (`VPhoneLaunchpadLauncherPolicy`); without the launcher, Launchpad starts `vphone-cli` directly. Nothing is signed at build time: `VPhoneLaunchpad/Build/SignLaunchpad.sh` signs afterwards, and the team comes from the gitignored `Configuration/Developer.xcconfig`. Never commit a team ID.
-- Launchpad and `VPhone.bundle` match by series, the first two numbers of the version: Launchpad 2.2.3 works with any `VPhone.bundle` 2.2.x, and the reverse. Patch releases within a series must stay interchangeable in both directions. A change to anything Launchpad relies on in the bundle (`vphone-cli` arguments or output, `vphone-escalator`, the bundle layout or receipt) needs a new minor version and a raised `minimumBundleComponents` in `VPhoneLaunchpad/VPhoneLaunchpadShared/VPhoneLaunchpadBundleStore.swift`. `Documents/Downloads/README.md` states this rule to users.
+- Launchpad and `VPhone.bundle` match by series, the first two numbers of the version: Launchpad 2.2.3 works with any `VPhone.bundle` 2.2.x, and the reverse. Patch releases within a series must stay interchangeable in both directions. A change to anything Launchpad relies on in the bundle (`vphone-cli` arguments or output, `vphone-escalator`, the bundle layout or receipt) needs a new minor version and a raised `minimumBundleComponents` in `VPhoneLaunchpad/VPhoneLaunchpadShared/VPhoneLaunchpadBundleStore.swift`. `Documents/en/get-started/downloads.md` states this rule to users.
- Host VM artifacts, caches, and archives created by vphone use mode `0777` for workstation access. Symlinks are not followed when changing permissions. Guest filesystem modes inside `Disk.img` remain unchanged.
- `VPhoneRestore` runs in the CLI process over vendored libirecovery and idevicerestore. No Python or runtime Homebrew dependency is allowed.
- The VM process owns AppKit windows and the guest control connection. `vphoned` serves HTTP and WebSocket over VSOCK 1339, with camera data on 1338.
diff --git a/Documents/Guides/bundle-integration.md b/Documents/Guides/bundle-integration.md
deleted file mode 100644
index 7a907692..00000000
--- a/Documents/Guides/bundle-integration.md
+++ /dev/null
@@ -1,65 +0,0 @@
-# VPhone bundle integration
-
-The `VPhone` Xcode scheme produces `VPhone.bundle`. It is a container for
-executables and resources, not a macOS app or a dynamically loaded plug-in.
-An integrating application such as `vphone-launchpad` should keep the bundle intact and launch
-`Contents/MacOS/vphone-cli` as a process. The CLI locates its companion
-`vphone-vm` by resolving its own executable path.
-
-| Path | Role |
-| --- | --- |
-| `Contents/MacOS/vphone-cli` | Unentitled command entry point |
-| `Contents/MacOS/vphone-vm` | VM and window process; private virtualization entitlements |
-| `Contents/MacOS/vphone-escalator` | AMFI allowlist tool for the current VM cdhash |
-| `Contents/MacOS/libswiftCompatibilitySpan.vphone.dylib` | Swift back-deployment library for `vphone-vm` on macOS 15 |
-| `Contents/Resources/guest-resources/vphoned` | Pre-signed guest daemon with its own entitlements; the bundle contains no unsigned copy |
-| `Contents/Resources/guest-resources/*.dylib` | Guest libraries: launchd hook, SystemHook, camera hooks, the GPU compiler plugin, and the fixes and device adapters listed in [`VPhoneGuestComponents`](../../VPhoneGuestComponents/README.md) |
-| `Contents/Resources/guest-resources/*.plist` | Guest launch daemon configuration, camera hook and MISFix filters |
-| `Contents/Resources` | Localized strings; no signing script or entitlement file is shipped |
-
-`Contents/MacOS` holds only programs that run on the Mac.
-`guest-resources` holds only files installed into the guest; every Mach-O in
-it is built for iOS. `ValidateBundle.sh` enforces both rules.
-Launchpad refuses a bundle older than `minimumBundleComponents` (set in
-`VPhoneLaunchpad/VPhoneLaunchpadShared/VPhoneLaunchpadBundleStore.swift`) and
-does not load older bundle layouts. Bundle 2.1.0 added patch presets
-(`fw patches`, `fw set-patches`, `fw patch --preset`) and the
-`vphone-escalator` executable.
-
-All executable payloads use ad hoc code signatures. Only the required child
-processes carry private entitlements. The bundle has no `CFBundleExecutable`,
-app launcher, SMJobBless helper, installer, password prompt, or automatic root
-acquisition. The integrating application owns download, release verification,
-host authorization, installation, and update policy. Developer Tools access
-and AMFI authorization are separate host decisions.
-
-macOS asks for a privacy permission (microphone, location) on behalf of the
-responsible process and ties the grant to its code signature. When
-`vphone-cli` is started with responsibility disclaimed, it becomes the
-responsible process for `vphone-vm`; it is signed ad hoc, so each new bundle
-build is asked again. An integrating application that starts `vphone-cli` as
-an ordinary child of a process with a stable signature, without disclaiming
-responsibility, gets the permission asked once. Launchpad does this with
-`vphone-launchpad-launcher`, which it carries in its own `Contents/MacOS`.
-macOS attributes a tool there to the enclosing app, so the prompt, the usage
-description and the grant are the app's. Under the hardened runtime the app's
-main executable must carry the matching resource entitlement
-(`com.apple.security.device.audio-input`,
-`com.apple.security.personal-information.location`); without it macOS refuses
-the request without asking.
-
-Install and update the whole bundle as one versioned unit. Do not rewrite a
-signed binary in place. When `vphone-vm` changes, its cdhash changes; the
-integrating application must arrange AMFI admission for the new build before
-launching it. The VM library and caches stay outside `VPhone.bundle`, under
-`~/.vphone` by default. Host-side VM outputs use mode `0777` so a separate
-workstation process can access them, including after a root-run create.
-Guest filesystem permissions inside `Disk.img` retain their own semantics.
-
-Build and validate:
-
-```sh
-xcodebuild -workspace VPhone.xcworkspace -scheme VPhone \
- -configuration Debug -destination 'platform=macOS,arch=arm64' \
- -derivedDataPath .build/XcodeBundle build
-```
diff --git a/Documents/Guides/core-bundles.md b/Documents/Guides/core-bundles.md
deleted file mode 100644
index aa04ad05..00000000
--- a/Documents/Guides/core-bundles.md
+++ /dev/null
@@ -1,80 +0,0 @@
-# Core Bundles and local builds
-
-[Documentation](../README.md) · [Launchpad command line](launchpad-cli.md) · [Bundle integration](bundle-integration.md)
-
-## One bundle per machine
-
-Every machine is bound to one installed `VPhone.bundle` version, chosen when
-it is created and kept in `launchpad.json` in the machine folder. Installing a
-bundle never changes a machine's binding. A machine is made of three layers,
-each from a bundle at a different time:
-
-| Layer | What | Comes from |
-| --- | --- | --- |
-| Host Programs | `vphone-cli`, `vphone-vm` | The bound bundle, on every command. A new binding applies at the next start. |
-| Guest Environment | vphoned and the hook dylibs | `cfw install` at creation, and `cfw update-environment` (stopped machine) later. |
-| Boot Chain | Patched firmware, restore, CFW patches | `fw patch`, `restore` and `cfw install` at creation. After that, `vphone-cli fw set-patches` changes the choice and `vphone-cli fw patches <vm>` lists what has not reached the guest: guest patches apply at the next `cfw update-environment`, AVPBooter at the next `fw patch`, a kernel patch with `cfw update-kernel` (data-preserving, no restore tree needed), and the rest of the boot chain (TXM, DeviceTree, LLB) only with a restore, which erases the guest. Launchpad shows the count in the inspector. |
-
-The **default** bundle (formerly "active") decides only the version
-`vm create` binds when `--bundle` is not given, and what `exec` and
-library-wide commands run with. A new install becomes the default unless
-`--keep-default` is passed. The first start of a machine in a Launchpad
-session checks its bundle (execution policy exception, AMFI, host preflight)
-once.
-
-Local builds install as `<version>-local.<hash>`, the hash taken from the
-bundle's code-signature seal, so two builds of one version sit side by side.
-Older stores may still hold `<version>-local` or `<version>-ci.<commit>`.
-
-## Testing a VPhone.bundle build
-
-For the one-time kernel and guest update that enables persistent shader caches
-on an existing VM, see [Persistent shader caches](shader-cache.md).
-
-```sh
-xcodebuild -workspace VPhone.xcworkspace -scheme VPhone \
- -configuration Debug -destination 'platform=macOS,arch=arm64' \
- -derivedDataPath .build/XcodeBundle build
-
-# Installs as <version>-local.<hash>, makes it the default, adds the execution
-# policy exception, allows the new vphone-vm cdhash and runs host preflight.
-vphone-launchpad-cli bundle install-local .build/XcodeBundle/Build/Products/Debug/VPhone.bundle
-
-# Move an existing machine to it; --update-environment also redeploys the
-# new vphoned and hook dylibs (the machine must be stopped).
-vphone-launchpad-cli vm set-bundle research-01 2.4.0-local.1a2b3c4d --update-environment
-
-vphone-launchpad-cli vm start research-01 --wait
-vphone-launchpad-cli guest rpc research-01 device.info
-vphone-launchpad-cli guest rpc research-01 apps.list '{}'
-vphone-launchpad-cli vm log research-01 --lines 100
-vphone-launchpad-cli vm stop research-01
-```
-
-The exact version is in the install result and in `bundle list`. The first
-step that needs the helper after its five-minute authorization expires asks
-for an administrator password on the Mac, as the window does.
-
-## Comparing two builds
-
-Install both without moving the default, then give each its own machine:
-
-```sh
-vphone-launchpad-cli bundle install-local /path/to/A/VPhone.bundle --keep-default
-vphone-launchpad-cli bundle install-local /path/to/B/VPhone.bundle --keep-default
-vphone-launchpad-cli bundle list # note both versions
-
-vphone-launchpad-cli vm create cmp-a --bundle 2.4.0-local.aaaaaaaa
-vphone-launchpad-cli vm create cmp-b --bundle 2.4.0-local.bbbbbbbb
-```
-
-Machines created this way differ in all three layers. To compare only host
-programs and guest environment on one boot chain, clone a machine in the
-window and rebind the copy:
-
-```sh
-vphone-launchpad-cli vm set-bundle cmp-b 2.4.0-local.bbbbbbbb --update-environment
-```
-
-`vm list` shows which bundle each layer came from. `bundle remove` refuses a
-version while a machine is bound to it; rebind or delete those machines first.
diff --git a/Documents/Guides/create-and-run.md b/Documents/Guides/create-and-run.md
deleted file mode 100644
index 7974843f..00000000
--- a/Documents/Guides/create-and-run.md
+++ /dev/null
@@ -1,67 +0,0 @@
-# Create and run a VM
-
-[Documentation](../README.md) · [Host setup](host-setup.md) · [Compatibility](compatibility.md)
-
-The public firmware workflow has one mode. A patch preset selects which patches apply (see [Templates](templates.md) for how presets enter the template key), and `--block` or `--allow` adjusts single patches. It patches the boot chain and guest system, installs vphoned, and leaves the user's environment empty. It does not install Sileo, apt, TrollStore, an SSH server or VNC server.
-
-## One-command flow
-
-Supply an iPhone17,3 restore IPSW and a compatible PCC/cloudOS IPSW as local paths or URLs. [Compatibility](compatibility.md) records the pairs actually verified here.
-
-```sh
-vphone-cli host preflight
-vphone-cli vm create myphone \
- --iphone-source /path/to/iPhone17,3_Restore.ipsw \
- --cloudos-source /path/to/cloudOS.ipsw
-```
-
-Creation runs prepare → firmware patch → online DFU restore → host-mounted CFW installation → first GUI boot. It needs network access for the restore ticket. The caller must provide root privileges for CFW installation; this bundle has no authorization dialog or privilege helper. The default virtual disk is 64 GB. `--keep-artifacts` retains the large prepared restore tree; omit it when disk space matters.
-
-By default that pipeline builds a [template](templates.md) rather than the VM itself, and the VM is cloned from it. The next `vm create` for the same device, iOS and cloudOS builds, preset and disk size clones from the same template instead of restoring again. Pass `--no-template` to build the VM on its own, as before.
-
-`--iphone-version` or `--iphone-build` instead of `--iphone-source` resolves the IPSW as `fw prepare` does, for `--device` (iPhone17,3 by default). Without `--cloudos-source` the cloudOS is the one the catalog recommends for that release, as `fw catalog` lists it.
-
-`--cpu`, `--memory`, `--network` and `--unlock-at-startup` set those `vm config` settings on the new VM (defaults: 8 cores, 8192 MB, nat, off). `--skip-first-boot` leaves out the final boot, for a caller that boots the VM itself.
-
-Before patching, creation prepares the firmware: a temporary cloudOS restore supplies the GPU driver, and a cloudOS without vphone600 components needs a rebuilt kernelcache. See [Firmware preparation](firmware-preparation.md). To create several machines from one list, see [Create many machines](many-machines.md).
-
-## Start and stop
-
-Success ends with `First boot: vphoned ping succeeded` and `JB VM created; vphoned connected`. **The verification VM is then stopped.** The ping proves the daemon answered over the host control socket during that boot; it does not leave a running VM behind.
-
-```sh
-vphone-cli vm launch myphone # start the VM window and keep it running
-vphone-cli vm stop myphone # run from another terminal to stop it
-```
-
-Closing the VM window, ⌘Q, `vm stop` and Control-C in the `vm launch` terminal all shut the guest down first (vphoned `system.shutdown`) and end the virtual machine once the guest has stopped, or after 15 seconds if it has not. A guest vphoned cannot answer for, such as one in DFU or still starting up, is turned off at once, as pulling the power would. A second Control-C turns it off without waiting. `vm stop` only ever signals the machine's own processes, `vphone-vm` and Virtualization's VM service; another program that has the disk open, such as Launchpad measuring its size, Spotlight or a backup tool, is named and left running.
-
-`vm launch` starts the guest without waiting for vphoned; the daemon connects during boot. The VM window and menu provide Home/power keys, app installation and file browsing. The host control socket is `<VM bundle>/vphone.sock`: one JSON line in, one out. Connections are served concurrently, and the socket also exists with `--no-graphics`, where `tap` and `swipe` go through vphoned's touch injection and screen images come from the guest. Besides `tap`, `swipe`, `key` and `screenshot`, `{"t":"rpc","method":"<vphoned method>","params":{…}}` calls any method in `Research/vphoned_http_api.md`. For example, `input.key` with `{"name":"cmd+v"}` pastes and `input.type` types text. No SSH or VNC endpoint is installed by this workflow.
-
-## Manual stages
-
-Use these when investigating or repeating one phase. Keep a DFU boot running while `restore` talks to it:
-
-```sh
-vphone-cli vm new myphone
-vphone-cli fw prepare myphone \
- --iphone-source /path/to/iPhone17,3_Restore.ipsw \
- --cloudos-source /path/to/cloudOS.ipsw
-vphone-cli fw patch myphone
-
-vphone-cli vm launch myphone --dfu &
-vphone-cli restore myphone
-vphone-cli vm stop myphone
-
-vphone-cli cfw install myphone
-vphone-cli vm launch myphone
-```
-
-The online restore obtains its ticket in process. For an offline restore, see `vphone-cli restore --help` for `--get-shsh` and `--offline`. The manual flow does not perform the automatic first-boot ping check from `vm create`.
-
-## Further reading
-
-- [Templates](templates.md): how `vm create` reuses one restore for many machines, and how to slim, find and delete templates.
-- [Device name and clock](device-name-and-clock.md): what the guest takes from the VM and the Mac.
-- [Library, firmware and backups](library-and-backups.md): where machines and caches live, clones and exports.
-- [Sharing disk space between VMs](sharing-disk-space.md): `vm rebase`.
diff --git a/Documents/Guides/device-name-and-clock.md b/Documents/Guides/device-name-and-clock.md
deleted file mode 100644
index 230fb968..00000000
--- a/Documents/Guides/device-name-and-clock.md
+++ /dev/null
@@ -1,11 +0,0 @@
-# Device name and clock
-
-[Documentation](../README.md) · [Create and Run](create-and-run.md) · [Networking](networking.md)
-
-## Device name
-
-The guest shows the VM's name as its device name, in Xcode's device list and `xcrun devicectl list devices`, and cannot be renamed from inside the guest or from Finder, Xcode or `idevicename`: a rename there reports success and changes nothing. `vphone-vm` hands the name to the guest each time it connects to vphoned, a few seconds into every boot, and the guest keeps it for the next boot. After `vm rename`, Finder and `ideviceinfo` see the new name as soon as the machine is up; Xcode and `devicectl` read it when the device appears and may show the old name until the following boot. An existing machine moved to a bundle with this feature receives the guest library with its environment update and uses it from the boot after that. The guest's own name stays in its preferences, untouched. A VM name of more than 255 UTF-8 bytes, or with a control character, is not used, and the guest shows its own name. See `Research/Guest/device_name_pinning.md`.
-
-## Clock and time zone
-
-The guest follows the Mac's time zone and clock. `vphone-vm` sends the Mac's zone each time it connects to vphoned, and the Mac's time then and every minute after, so a guest that was off for a day, or sat under a sleeping Mac, is back on the Mac's time within a minute without reaching an NTP server. A guest within a second of the Mac is left alone. To give the guest another date or time, pick it in the guest's Settings › General › Date & Time: that turns its automatic time off and the Mac's time is no longer applied. Turning Set Automatically on there brings the Mac's time back.
diff --git a/Documents/Guides/firmware-preparation.md b/Documents/Guides/firmware-preparation.md
deleted file mode 100644
index 394c4548..00000000
--- a/Documents/Guides/firmware-preparation.md
+++ /dev/null
@@ -1,13 +0,0 @@
-# Firmware preparation
-
-[Documentation](../README.md) · [Create and Run](create-and-run.md) · [Compatibility](compatibility.md)
-
-What `vm create` and `fw prepare` do with the two IPSWs before the firmware is patched.
-
-`fw prepare` creates a temporary vphone VM with no network device, starts it in DFU, and restores the selected cloudOS IPSW using this project's restore backend. It mounts the restored System volume read-only, extracts the GPU bundle, then removes the temporary VM. This first restore supplies the GPU driver for the second, hybrid iPhone restore. The extracted bundle is cached per cloudOS build in `~/.vphone/gpu-drivers/`, so later machines on the same cloudOS skip the temporary restore. `vm create` and `fw prepare` also accept `--gpu-driver-bundle /path/to/AppleParavirtGPUMetalIOGPUFamily.bundle` to reuse a previously extracted bundle without the temporary restore. The CLI checks its iPhoneOS platform version against the selected cloudOS version. Each restore obtains its own ticket online.
-
-A cloudOS after the 26.4 beta has no vphone600 components, and the research board stands in ([Compatibility](compatibility.md)). Its kernelcache is rebuilt with the vphone600 virtualization kexts. KDK extraction runs natively; only the kmutil link needs root. After `fw prepare`, stage the mix as yourself with `vphone-cli fw kernelcache <vm>`, link it with `sudo vphone-cli fw kernelcache <vm> --link-only`, and continue with `fw patch` as usual. The old `--ipsw` argument is still accepted but ignored.
-
-A kernel only boots in the layout Apple linked it with, and kmutil takes the layout from the Mac it runs on: macOS 26.4 and later link the iOS 26.4+ kernelcaches (kernel-last), macOS 15 and 26.0–26.3 the older ones (kernel-first). When this Mac has the other layout, another Mac or a macOS VM links the mix over ssh: set `VPHONE_KMUTIL_SSH=<user>@<host>` (and `VPHONE_KMUTIL_SSH_PASSWORD=<password>` without ssh keys and passwordless sudo there) for `fw kernelcache` or the creation. The staged volume is uploaded to that Mac's `/private/var/tmp`, linked there as root and removed; nothing on this Mac needs root for it. Remote Login must be on, and the user must be allowed to use sudo.
-
-The build also ships an arm64e GPU compiler plugin in the bundle. `fw prepare` copies it into the staged GPU bundle before firmware patching and installation.
diff --git a/Documents/Guides/host-setup.md b/Documents/Guides/host-setup.md
deleted file mode 100644
index 3b85f899..00000000
--- a/Documents/Guides/host-setup.md
+++ /dev/null
@@ -1,67 +0,0 @@
-# Host setup
-
-[Documentation](../README.md) · [Create a VM](create-and-run.md) · [Troubleshooting](troubleshooting.md)
-
-The VM needs an Apple Silicon Mac running macOS 15 or newer. PV=3 research guests do not run inside a nested macOS VM. The signed `vphone-vm` companion carries Apple-private virtualization entitlements; the unentitled `vphone-cli` entry point can still print a useful error if the host refuses it.
-
-## Build and preflight
-
-A distributed `VPhone.bundle` needs no Homebrew, Python or Xcode **at runtime**. A source build needs Xcode and its iPhoneOS SDK to compile vphoned. From a source checkout:
-
-```sh
-xcodebuild -workspace VPhone.xcworkspace -scheme VPhone \
- -configuration Debug -destination 'platform=macOS,arch=arm64' \
- -derivedDataPath .build/XcodeBundle build
-.build/XcodeBundle/Build/Products/Debug/VPhone.bundle/Contents/MacOS/vphone-cli host preflight
-```
-
-Build the `VPhone` scheme in Xcode to produce the ad hoc signed bundle with all companion binaries. `host preflight` checks the entitled companion before any VM is started. If AMFI refuses it, the error prints the bundled allowlist helper command.
-
-## Permit the entitled VM binary
-
-These are host policy choices, performed by the machine owner. Both require `csrutil allow-research-guests enable` in Recovery. Choose one path.
-
-### A. Disable SIP and AMFI
-
-In macOS Recovery, open Terminal:
-
-```sh
-csrutil disable
-csrutil allow-research-guests enable
-```
-
-After rebooting into macOS, set the boot argument and reboot again:
-
-```sh
-sudo nvram boot-args="amfi_get_out_of_my_way=1 -v"
-```
-
-This is the more permissive host configuration. Review existing `boot-args` before replacing them.
-
-### B. Keep SIP enabled with debugging restrictions relaxed
-
-In macOS Recovery:
-
-```sh
-csrutil enable --without debug
-csrutil allow-research-guests enable
-```
-
-After rebooting, allowlist the **current signed build**. In a source checkout:
-
-```sh
-bundle=.build/XcodeBundle/Build/Products/Debug/VPhone.bundle
-sudo "$bundle/Contents/MacOS/vphone-escalator" allow "$bundle/Contents/MacOS/vphone-vm"
-"$bundle/Contents/MacOS/vphone-escalator" status
-"$bundle/Contents/MacOS/vphone-cli" host preflight
-```
-
-The helper creates the AMFI code-requirements preference if absent. If it exists, it appends the current `vphone-vm` cdhash to its `Entitlements` requirement, preserving other cdhashes and preference keys. It leaves any existing `AllowUnsafeDynamicLinking` value untouched and writes `false` only when that key is absent. It avoids duplicate hashes and enables amfid to consult the requirement by changing one byte in its heap. **Repeat the `allow` command after every build**, including a rebuild that only changes the signature. You may pass additional signed host binaries to the same `allow` command when they need restricted entitlements; the unentitled `vphone-cli` does not need this. `sudo "$bundle/Contents/MacOS/vphone-escalator" off` removes only hashes added by this helper and restarts amfid. It preserves the preference and its other values.
-
-For a distributed bundle without a source checkout, run `vphone-cli host preflight` first. If AMFI refuses `vphone-vm`, the preflight error gives the full `sudo .../vphone-escalator allow .../vphone-vm` command for that bundle.
-
-In `vphone-launchpad`, bundle preflight checks that SIP debugging restrictions are disabled (or SIP is fully disabled) and Research Guests is enabled. When a newer app includes a newer SMJobBless helper, Launchpad asks for administrator authorization to update the helper at startup. If the installed `vphone-vm` is blocked by AMFI, the helper checks those host settings again, verifies the root-owned bundle and its recorded cdhash, runs that bundle's `vphone-escalator allow` as root, and Launchpad repeats preflight. Each new bundle signature is checked and allowed separately. The standalone CLI still reports the manual command.
-
-## What the build contains
-
-`vphone-cli` orchestrates the work without private entitlements and handles archives through `vphone-cli archive`. `vphone-vm` is the signed, entitled GUI/VM process. The bundle also contains `vphoned`, compiled for iOS at build time; it is installed into each created guest. The [research notes on the binary split](../../Research/Host/host_binary_split.md) record the implementation history, including superseded approaches.
diff --git a/Documents/Guides/ipados.md b/Documents/Guides/ipados.md
deleted file mode 100644
index 7943d4a5..00000000
--- a/Documents/Guides/ipados.md
+++ /dev/null
@@ -1,114 +0,0 @@
-# iPadOS guests
-
-[Documentation](../README.md) · [Create and Run](create-and-run.md) · [Compatibility](compatibility.md)
-
-A vphone VM can run iPadOS instead of iOS. Nothing about the virtual hardware
-changes: the boot chain, kernel, SEP and device tree still come from the PCC
-cloudOS IPSW (`vresearch101ap` / `vphone600ap`). Only the userland comes from a
-different restore IPSW, an iPad's instead of the iPhone17,3's, and the device
-tree is rewritten so that userland sees an iPad.
-
-![iPadOS home screen in a vphone VM](../ipados-demo.jpeg)
-
-## Supported devices
-
-| Product | Model | Board | Panel | Points @2x |
-| --- | --- | --- | --- | --- |
-| `iPad16,1` | iPad mini (A17 Pro) | J410AP | 1488x2266 @ 326 ppi | 744x1133 |
-| `iPad15,7` | iPad (A16) | J481AP | 1640x2360 @ 264 ppi | 820x1180 |
-| `iPad15,3` | iPad Air 11-inch (M3) | J607AP | 1640x2360 @ 264 ppi | 820x1180 |
-| `iPad15,5` | iPad Air 13-inch (M3) | J637AP | 2048x2732 @ 264 ppi | 1024x1366 |
-| `iPad16,3` | iPad Pro 11-inch (M4) | J717AP | 1668x2420 @ 264 ppi | 834x1210 |
-| `iPad16,5` | iPad Pro 13-inch (M4) | J720AP | 2064x2752 @ 264 ppi | 1032x1376 |
-| `iPad17,1` | iPad Pro 11-inch (M5) | J817AP | 1668x2420 @ 264 ppi | 834x1210 |
-| `iPad17,3` | iPad Pro 13-inch (M5) | J820AP | 2064x2752 @ 264 ppi | 1032x1376 |
-
-The cellular models (`iPad16,2`, `iPad15,4`, `iPad15,6`, `iPad16,4`, `iPad16,6`,
-`iPad17,2`, `iPad17,4`) share their Wi-Fi twin's IPSW and run as it: the VM has
-no baseband. `iPad15,8` ships in an IPSW of its own without the Wi-Fi board and
-is not supported.
-
-Most iPad IPSWs cover several models — the iPad Air and iPad Pro IPSWs carry
-both sizes. Without `--device`, `fw prepare` takes the first model the IPSW
-lists (the 11-inch); pass `--device iPad17,3` to `fw prepare` or `vm create` for
-the 13-inch. Launchpad's New Machine passes the model chosen under **Device**;
-with **Custom IPSWs** it takes the first.
-
-Adding another iPad takes one line in `VPhoneGuestDevice`: its product type,
-board and panel. Everything the device tree needs is read from the board's own
-`DeviceTree.<board>.im4p` in the IPSW.
-
-## Create one
-
-Pass the iPad restore IPSW where the iPhone one would go. The cloudOS is the
-same one an iPhone guest of that release would use. `fw catalog` lists every
-supported iPad's iPadOS releases with that cloudOS, and `fw catalog --device
-iPad16,1` lists one iPad's. With `--device` and no sources, `vm create` offers
-that iPad's releases to choose from.
-
-```sh
-vphone-cli vm create ipad-mini \
- --iphone-source 'https://updates.cdn-apple.com/2026SummerFCS/cf7db64d-5866-4bf2-bfff-50a32f58bec3/iPad16,1,iPad16,2_26.6.2_23G90_Restore.ipsw' \
- --cloudos-source 'https://updates.cdn-apple.com/private-cloud-compute/c0ecdb4b310cf5239ab2b248dd3098eec297dc5aa3bbe6ada27273262b0b8b64'
-
-# The 13-inch iPad Pro (M5), from the IPSW that also carries the 11-inch
-vphone-cli vm create ipad-pro-13 --device iPad17,3 \
- --iphone-source 'https://updates.cdn-apple.com/2026SummerFCS/<…>/iPad17,1,iPad17,2,iPad17,3,iPad17,4_26.6.2_23G90_Restore.ipsw' \
- --cloudos-source 'https://updates.cdn-apple.com/private-cloud-compute/c0ecdb4b310cf5239ab2b248dd3098eec297dc5aa3bbe6ada27273262b0b8b64'
-```
-
-`fw prepare --device iPad16,1 --list` lists the iPad's downloadable IPSWs,
-and `--device iPad16,1 --iphone-version 26.6.2` resolves one.
-
-In Launchpad, choose **New Machine**, pick the iPad under **Device** and an
-iPadOS release under **iPadOS**; the recommended cloudOS comes with it. For an
-IPSW that is not in the catalog, set **Source** to **Custom IPSWs** and put the
-iPad IPSW in the **iPhone IPSW** field and the cloudOS IPSW in the other. The
-Core Bundle in use must include iPad support; the **Device** menu appears only
-with a Core Bundle whose catalog lists iPads. `vphone-launchpad-cli vm create
-<name> --device iPad16,1` does the same from a terminal.
-
-The manual stages are the same as for an iPhone guest (`vm new`,
-`fw prepare`, `fw patch`, DFU + `restore`, `cfw install`, `vm launch`).
-Only `fw prepare` and `fw patch` differ for an iPad; DFU, `restore` and
-`cfw install` run unchanged.
-
-## What changes for an iPad
-
-- **`fw prepare`** recognizes the IPSW from its `SupportedProductTypes`, takes
- the erase identity and `DeviceMap` entry for the guest's board (an iPad IPSW
- covers several), and records the product type and the iPad's display in the
- VM's `config.plist` (`guestProductType`, `screenConfig`). The restore tree
- is named `iPhoneOS_iPad16,1_<version>_<build>_Restore`; the `iPhone` prefix
- is the restore-tree convention every reader matches, not the device.
-- **Two device trees.** The hybrid manifest normally points `DeviceTree` and
- `RestoreDeviceTree` at the same vphone600 file. For an iPad, `DeviceTree`
- points at a copy, `Firmware/all_flash/DeviceTree.vphone600ap.guest.im4p`.
- Restore boots the untouched identity that `restored_external` checks against
- the manifest (`iPhone99,11`); the guest boots the copy.
-- **`fw patch`** gives that copy the iPad's identity and presentation (patch
- set `devicetree`, entries `devicetree-cfw-ipad_*`):
- - root `model`, `target-type` and `target-sub-type` as on the board (for the
- iPad mini `iPad16,1`, `J410`, `J410AP`), and `compatible` with the board
- first and `VPHONE600AP` kept second;
- - `/product`: the board's artwork idiom, subtype and scale, product name,
- chrome, camera and button geometry, multitasking capabilities
- (`medusa-overlay-app-capability`, `ui-floating-live-app`, `ui-overlay-app`,
- `ui-pinned-app`, and `disable-chamois` where the board has no Stage
- Manager), and its product type and unique model — all read from the
- board's `DeviceTree.<board>.im4p`, which the restore tree keeps;
- - phone-only `syscfg` placeholders (Dynamic Island, reachability, ringer
- switch, volume-button geometry, CarPlay, Watch pairing) are removed.
-
- The virtual hardware keeps its vphone600 description: GPU feature set,
- framebuffer, memory class and boot flags.
-- **LLB** gets one more patch on an iPad guest, `llb-cfw-display_scale`. LLB
- fills `/chosen/display-scale` from the paravirtual display's boot video
- word, which always says 3x; MobileGestalt turns that property into the
- screen scale, so an iPad would get a 496x755-point canvas. The patch makes
- LLB write the iPad's own scale (2x, 744x1133 points).
-- **`cfw install`** leaves the installed device tree alone. The iPhone17,3
- post-restore identity rewrite (`preboot-exp-devicetree_identity`) is skipped
- on an iPad guest.
-- **The VM window** follows `screenConfig`, so it opens at the iPad's aspect
- ratio.
diff --git a/Documents/Guides/iphone-models.md b/Documents/Guides/iphone-models.md
deleted file mode 100644
index f2654964..00000000
--- a/Documents/Guides/iphone-models.md
+++ /dev/null
@@ -1,64 +0,0 @@
-# Other iPhone models
-
-[Documentation](../README.md) · [Create and Run](create-and-run.md) · [iPadOS guests](ipados.md) · [Compatibility](compatibility.md)
-
-The guest's iOS can come from another iPhone's restore IPSW instead of the
-iPhone17,3's (iPhone 16). As with an iPad guest, the virtual hardware does not
-change: the boot chain, kernel, SEP and device tree still come from the PCC
-cloudOS IPSW (`vresearch101ap` / `vphone600ap`). Only the userland comes from
-the chosen model's IPSW, and the device tree the guest boots is rewritten to
-present that model.
-
-## Supported devices
-
-| Product | Model | Board | Panel | Points @3x |
-| --- | --- | --- | --- | --- |
-| `iPhone17,3` | iPhone 16 | D47AP | 1290x2796 @ 460 ppi | 430x932 |
-| `iPhone17,4` | iPhone 16 Plus | D48AP | 1290x2796 @ 460 ppi | 430x932 |
-| `iPhone17,1` | iPhone 16 Pro | D93AP | 1206x2622 @ 460 ppi | 402x874 |
-| `iPhone17,2` | iPhone 16 Pro Max | D94AP | 1320x2868 @ 460 ppi | 440x956 |
-| `iPhone17,5` | iPhone 16e | V59AP | 1170x2532 @ 460 ppi | 390x844 |
-| `iPhone18,3` | iPhone 17 | V57AP | 1206x2622 @ 460 ppi | 402x874 |
-| `iPhone18,4` | iPhone Air | D23AP | 1260x2736 @ 460 ppi | 420x912 |
-| `iPhone18,1` | iPhone 17 Pro | V53AP | 1206x2622 @ 460 ppi | 402x874 |
-| `iPhone18,2` | iPhone 17 Pro Max | V54AP | 1320x2868 @ 460 ppi | 440x956 |
-| `iPhone18,5` | iPhone 17e | V159AP | 1170x2532 @ 460 ppi | 390x844 |
-| `iPhone19,2` | iPhone 18 Pro | V63AP | 1206x2622 @ 460 ppi | 402x874 |
-
-Every model, the iPhone17,3 included, gets its panel and the identity from its
-own device tree; the iPhone17,3's panel is the display it has always had.
-Each model has an IPSW of its own, so `--device` is not needed. `fw catalog`
-lists the iPhone 16/17 models' releases from 26.0 to 27.0.1 (the iPhone 17e
-from 26.3.1), and the iPhone 18 Pro's 27.0.1,
-each with the cloudOS an iPhone17,3 of that release uses, and `fw catalog
---device iPhone18,1` lists one model's.
-
-The iPhone 17 Pro, 17 Pro Max and 18 Pro have recorded boot validation; see
-[Compatibility](compatibility.md). iPhone19,2 uses ARM64E_X1. On hosts without
-native X1 support, the standard preset lowers unsupported instructions; this
-weakens PC-bound pointer authentication.
-
-## Create one
-
-```sh
-vphone-cli vm create iphone17pro \
- --iphone-source 'https://updates.cdn-apple.com/2026SummerFCS/f768ecdf-e037-44e6-bfa6-949b6d127c4f/iPhone18,1_26.6.2_23G90_Restore.ipsw' \
- --cloudos-source 'https://updates.cdn-apple.com/private-cloud-compute/c0ecdb4b310cf5239ab2b248dd3098eec297dc5aa3bbe6ada27273262b0b8b64'
-```
-
-In Launchpad, choose **New Machine**, pick the model under **Device** and a
-release under **iOS**. `vphone-launchpad-cli vm create <name> --device
-iPhone18,1` does the same from a terminal.
-
-## What changes for another iPhone
-
-Everything [iPadOS guests](ipados.md#what-changes-for-an-ipad) lists, with two
-differences:
-
-- The board's `/product` values replace the vphone600 placeholders the same
- way, but an iPhone board keeps the phone properties it has: Dynamic Island,
- reachability, OLED, volume-button geometry, CarPlay and Watch pairing come
- from the board instead of being removed. The patch IDs are the
- `devicetree-cfw-ipad_*` ones; they were named before iPhones used them.
-- LLB is not patched for the display scale. The paravirtual display's boot
- video word says 3x, which is already an iPhone's scale.
diff --git a/Documents/Guides/launchpad-cli.md b/Documents/Guides/launchpad-cli.md
deleted file mode 100644
index af6d67e0..00000000
--- a/Documents/Guides/launchpad-cli.md
+++ /dev/null
@@ -1,126 +0,0 @@
-# Launchpad command line
-
-[Documentation](../README.md) · [Core Bundles and local builds](core-bundles.md)
-
-`vphone-launchpad-cli` ships in `vphone-launchpad.app/Contents/MacOS`. It
-drives the running Launchpad over a Unix socket at
-`~/Library/Application Support/vphone-launchpad/control.sock` (mode 0600,
-served only to the same user) and starts Launchpad when it is not running. It
-has no privileges and no state of its own: bundles are installed through
-Launchpad's helper, each machine runs through the `vphone-cli` of its own Core
-Bundle, and every command appears in Launchpad's window and command history.
-Nothing listens on the network; reach it over ssh from another machine.
-
-A Launchpad the CLI starts opens hidden and does not take focus from the app
-in front; click its Dock icon, or Open Launchpad in the menu bar, to show the
-window. Pass `--foreground` (before the command, or among the options of any
-command but `exec`) to start it with its window in front instead. Neither
-changes a Launchpad that is already running.
-
-Progress lines go to stderr as they arrive. The result is one JSON document on
-stdout. The exit status is 0 on success and 1 on failure, with the reason on
-stderr. Interrupting the CLI cancels a command that can be cancelled
-(`exec`, waits, CFW install); a bundle install or machine creation belongs to
-the window and keeps running.
-
-```sh
-ln -s /Applications/vphone-launchpad.app/Contents/MacOS/vphone-launchpad-cli /usr/local/bin/
-vphone-launchpad-cli help
-```
-
-Each machine runs through the `vphone-cli` of the bundle it is bound to. To install a local `VPhone.bundle` build, move a machine to it, or compare two builds, see [Core Bundles and local builds](core-bundles.md).
-
-## Commands
-
-| Command | Does |
-| --- | --- |
-| `status` | Host checks, helper, default bundle, machine counts |
-| `bundle list` | Installed versions, receipts, cdhashes, check results, bound machines |
-| `bundle install-local <path> [--keep-default]` | Install a local `VPhone.bundle` folder or `.zip` |
-| `bundle install-release <version\|latest> [--keep-default]` | Download and install a GitHub release |
-| `bundle set-default <version>` / `bundle verify <version>` | Make a version the default, or re-check it. `bundle use` is the old name of `set-default` |
-| `bundle accept <version> [--off]` / `bundle remove <version>` | Skip failed checks, or remove a version no machine is bound to |
-| `vm list` | Machines in every library with run state, Core Bundle and log path. Only a VM process holding the disk (`vphone-vm`, or Virtualization's VM service) makes a machine `running`; any other process that has it open (`tail`, Spotlight, a backup tool) is listed in `diskOpenIn` (`12925 tail`) and leaves it `stopped` |
-| `vm start <name> [--headless] [--wait]` / `vm stop <name>` | Launch with the machine's bundle, or stop; `--wait` waits for vphoned. Stop asks the guest to shut down (vphoned `system.shutdown`) and waits up to 30 s; when the guest cannot be asked or does not stop, it ends the virtual machine as before. Like `vphone-cli vm launch`, start is not refused by a process that only has the disk open; it prints a note naming it |
-| `vm wait <name>` / `vm log <name> [--kind create\|dfu\|patch]` | Wait for vphoned; read a console log |
-| `vm create <name> [--bundle <version>] [...] [--device <product-type>] [--preset <preset>] [--ipsw <path>] [--kmutil-ssh <user@host>] [--block <patch>]... [--allow <patch>]... [--no-template \| --slim on\|off --trim … --keep-languages … --service-profile … --remove-apps … --keep-apps … --accounts-off] [--from <step>]` | The New Machine pipeline, bound to `--bundle` or the default: cloned from a template, built first when missing (2.9), or restored on its own with `--no-template`; the slimming switches are `vphone-cli vm create`'s, except that Apple Account goes with the trimmed service profile as in New Machine (`--accounts-off` is accepted and changes nothing). `--preset` takes a preset name or the path of a preset plist (2.14), which the machine keeps a copy of. `--block`/`--allow` (repeatable) turn one patch of the preset off or on, as New Machine's patch list and `vphone-cli fw set-patches` do (see below). `--device` makes an iPad guest, or with `AppleTV5,3` an Apple TV HD guest, which is always restored on its own without slimming and takes the `tvos` preset unless `--preset` names another, and with `AppleTV14,1` an Apple TV 4K guest, the same with the `tvos-4k` preset and its userland from the catalog's OTA; `--preset minimal` (Minimal: a stock boot chain, kernel and TXM, with the system customized before the restore) is also restored on its own without slimming, and its `fw patch` runs as root through the helper (its Userspace debugging box, `userspace-debugging` under Features in `vphone-cli fw patches`, is an `--allow` for each patch it lists); the kernelcache mix of a machine whose cloudOS has no vphone600 components (its release's own cloudOS, a watch, an iOS 18 guest) is staged with `fw kernelcache` and linked by the helper as root; `--ipsw` is optional and only passed on to a 2.12.0 bundle, which stages with it, as New Machine's ipsw field (a 2.12.1 bundle extracts natively); `--kmutil-ssh` names the Mac that links an iOS 18 guest's (`--device iPhone11,6`) kernel-first mix over ssh, as New Machine's macOS builder field, and takes the password for ssh and sudo there from the client's `VPHONE_KMUTIL_SSH_PASSWORD`, never from an argument; `--from` retries from a step (`findTemplate` … `firstBoot`) with the options the creation started with; the result names the template, whether this creation built it, and the patches it used |
-| `vm set-bundle <name> <version> [--update-environment]` | Bind a machine to another installed version. `--update-environment` also redeploys that version's guest environment and needs a stopped machine; a disk another process has open refuses it, naming that process, before the binding changes. If the update itself fails, the machine stays bound to the new version and `vm list` still shows the old `guestEnvironmentBundle`: run `cfw update-environment` to finish |
-| `vm leases [--release]` | DHCP leases on the shared NAT network and the machine that owns each. `--release` frees the ones no machine in any library uses, through the helper (see [Networking](network-addresses.md#addresses-held-by-old-macs)) |
-| `cfw install <name>` | Install CFW into a stopped machine with its own bundle, through the helper. The helper puts temporary work files on the VM library's external volume when applicable. It and the two updates below refuse a disk another process has open, naming it (`12925 tail`). |
-| `cfw update-environment <name>` | Redeploy the machine's own bundle's guest resources (vphoned, hook dylibs) into it while stopped, through the helper; nothing else changes |
-| `cfw update-kernel <name>` | Re-patch the kernelcache from the machine's current selection and swap it into Preboot, keeping the data (VM off); the data-preserving way to change a kernel patch on an installed VM, no restore tree needed |
-| `guest send <name> <json>` | One raw `vphone.sock` request (tap, swipe, key, screenshot) |
-| `guest rpc <name> <method> [params]` | Any vphoned method, see `Research/vphoned_http_api.md`. When vphoned refuses it, the last stderr line is its error object as JSON (`code`, `message`, `results`, `reason` …) |
-| `guest push <name> <local> <guest-path> [--mode <octal>]` | Copy a Mac file into the guest. It streams through vphoned, so size is not limited by `guest rpc`'s 1 MiB JSON line; use it for binaries and IPAs. A guest path ending in `/` keeps the file's name; the mode defaults to the Mac file's permissions |
-| `guest pull <name> <guest-path> <local>` | Copy a guest file to the Mac, streamed; `local` may be a folder. The file replaces `local` only once complete |
-| `guest unlock <name> [--passcode <code>] [--timeout <seconds>]` | Turn the screen on and unlock the guest, whatever state it was in (vphoned `screen.unlock`). `--passcode` is needed only when the guest has one |
-| `exec [--bundle <version>] <vphone-cli arguments>` | Run the default bundle's `vphone-cli`, or that version's, streaming its output. `--bundle` must come first |
-
-Apple TV 4K (4th generation) uses `--device AppleTV18,1` with Launchpad and
-Core Bundle 2.13. It selects `tvos-4k`, restores independently without slimming,
-and takes tvOS 27.2 beta (`24K120`) from its full OTA over the Apple TV HD base.
-Creation requires macOS 27. A live boot is still pending; see the
-[bring-up notes](../../Research/Firmware/tvos_support.md#apple-tv-4k-4th-generation).
-
-### Patch overrides in `vm create`
-
-`--block <patch>` and `--allow <patch>` take the identifiers `vphone-cli fw
-patches` lists (`vphone-launchpad-cli exec fw patches --preset <preset>`),
-once per patch. Launchpad reads that catalog from the creation's bundle,
-refuses an identifier no patch set declares or one both blocked and allowed,
-and keeps only what differs from the preset, as `fw set-patches` does. It
-then splits them the way New Machine does:
-
-- Boot-chain patches (AVPBooter, iBSS, iBEC, LLB, TXM, kernelcache,
- DeviceTree …) are part of the template's key: Find Template looks for a
- template built with them, and a template build records them with `fw
- set-patches` before `fw patch`.
-- Guest patches stay out of the template. The clone records them with `fw
- set-patches`, and the Apply Guest Patches step writes them with `cfw
- update-environment` through the helper before the first boot. A guest
- override alone therefore reuses the plain template.
-
-```sh
-vphone-launchpad-cli vm create rt-e --block system-debugserver-cfw-install
-```
-
-The result's `patches` object holds the preset, the `blocked` and `allowed`
-overrides and the `guest` ones applied to the clone. With `--no-template`
-every override goes into the machine's own restore. `--from` refuses
-`--block` and `--allow`: a retry keeps the creation's patches.
-
-Machine commands take `--root <library>` when two libraries hold a machine
-with the same name. `guest` commands and `--wait` go through the machine's
-`vphone.sock`, which every launch serves; bundles up to 2.0.9 serve it only
-for machines launched with a window.
-
-## Bundle fields in results
-
-| Command | Field | Meaning |
-| --- | --- | --- |
-| `status` | `defaultBundle` | The default version. `activeBundle` holds the same value for older scripts |
-| `bundle list` | `default` | This version is the default. `active` holds the same value for older scripts |
-| `bundle list` | `machines` | Names of the machines bound to this version |
-| `vm list` | `bundle` | The version the machine's host programs run with |
-| `vm list` | `guestEnvironmentBundle` | The version whose guest environment was installed last; `null` while unknown |
-| `vm list` | `bootChainBundle` | The version that built the boot chain; `null` for a machine created before Launchpad recorded it |
-| `vm create`, `cfw …`, `exec` | `bundle` | The version the command ran with |
-
-When `guestEnvironmentBundle` differs from `bundle`, host and guest come from
-different builds; `cfw update-environment` brings the guest in line.
-
-`guest send <name> '{"t":"display.geometry"}'` reads the host's configured
-and captured pixel dimensions plus the live display-view bounds, rotation,
-aspect-fit drawing rect, and pointer/touch path. It does not change input or
-display state. Compare it with `device.screen`, `display.orientation` and
-actual guest event receipts when diagnosing rotated coordinate mismatches.
-
-Touch coordinates for `guest send` refer to the **full upright screenshot**
-returned by `t:screenshot`: after a quarter turn its width and height swap.
-The host converts that point into fixed-panel HID coordinates for both GUI
-and headless launches. `display.geometry.capture_pixels` is the raw host
-frame; `screenshot_pixels` and `input_orientation` describe input coordinates.
-A swipe keeps the geometry sampled at its start.
-
-Geometry changes across a screenshot cause an error rather than returning an
-image with ambiguous input coordinates.
diff --git a/Documents/Guides/library-and-backups.md b/Documents/Guides/library-and-backups.md
deleted file mode 100644
index c5184ef5..00000000
--- a/Documents/Guides/library-and-backups.md
+++ /dev/null
@@ -1,31 +0,0 @@
-# Library, firmware and backups
-
-[Documentation](../README.md) · [Create and Run](create-and-run.md) · [Sharing disk space](sharing-disk-space.md) · [Snapshots](snapshots.md)
-
-| Default path | Contents |
-| --- | --- |
-| `~/.vphone/machines/<name>/` | One VM, including its disk, `config.plist`, and patch work files |
-| `~/.vphone/ipsws/` | Remote source IPSWs, shared by every VM; local IPSWs are read in place |
-| `~/.vphone/gpu-drivers/<version>_<build>/` | GPU driver bundles extracted from cloudOS, shared by every VM |
-| `~/.vphone/kernelcache/` | Kernelcache mixes for cloudOS releases without vphone600 components, their staged volumes and the donor extraction |
-
-`VPHONE_ROOT` relocates the VM library and both caches. `VPHONE_LIBRARY_ROOT` takes precedence for the library alone, and `--ipsw-cache <dir>` on `vm create` and `fw prepare` for the IPSW cache alone. Downloaded IPSWs stay cached until you delete them (in Launchpad, with File > Downloaded IPSWs…), so a second VM from the same URL downloads nothing; the prepared restore tree is removed after a successful `vm create` unless `--keep-artifacts` is set. VMs prepared by an earlier build may still hold a `.ipsw-cache/` directory; it is safe to delete, and `vm export` leaves it out.
-
-A remote IPSW downloads over four connections at once when its server answers HTTP range requests, as Apple's CDN does; each connection fetches 32 MB segments in turn and resumes a dropped segment where it stopped. `--download-connections <n>` on `fw prepare` sets the count (1 to 16); 1 downloads the IPSW as a single stream, which is also what a server that ignores ranges gets.
-
-```sh
-vphone-cli vm list
-vphone-cli vm info myphone
-vphone-cli vm clone myphone copy
-vphone-cli vm clone myphone second --new-identity
-vphone-cli vm export myphone --out myphone.tzst
-vphone-cli vm import myphone.tzst --name restored
-```
-
-`vm clone` copies a stopped machine, using APFS copy-on-write when available; it refuses while the source runs. A plain copy keeps everything, including the device identity (machine identifier and MAC address), so it is a backup and cannot run beside the original.
-
-`--new-identity` makes a second device instead. The copy gets a new machine identifier (ECID), and with it a new UDID, and a new MAC address on its first start. Its fixed IPv4 address, port forwards and a hand-chosen mDNS name are cleared, since they would collide with the original's; an mDNS name `--mdns on` derived from the original's name follows the new name, as on rename. Set new ones with `vm config` if you need them. The guest keeps the original's data, apps and settings, and no restore is needed. Before lockdown tools such as `ideviceinstaller` work, unlock the copy and trust this Mac again. On APFS a copy shares its disk blocks with the original and holds only what it changes, about 0.35 GB after its first boots, although `du` and Finder report the full size for each.
-
-Do not swap `SEPStorage`, `nvram.bin` or the disk image between machines: they were made together by one restore, and a guest whose SEP storage does not match its disk panics at boot.
-
-Run resource-heavy creations **one at a time**. Both the IPSWs and temporary restore tree consume substantial disk space, and patching large caches can be memory intensive. Check free space before starting a second VM. Launchpad places CFW scratch files on the VM library's mounted external volume when applicable; standalone `vphone-cli cfw install` defaults to `/private/var/tmp` and accepts `--work-parent` for a root-owned private directory.
diff --git a/Documents/Guides/many-machines.md b/Documents/Guides/many-machines.md
deleted file mode 100644
index a58ec428..00000000
--- a/Documents/Guides/many-machines.md
+++ /dev/null
@@ -1,31 +0,0 @@
-# Create many machines
-
-[Documentation](../README.md) · [Create and Run](create-and-run.md) · [Templates](templates.md)
-
-`vm create-bulk <list.plist>` creates every machine a plist describes. Each key is a `vm create` option's long name, with its value: a string or integer, `true` for a flag, an array for `keep-apps`. `defaults` apply to every machine, a machine's own keys win, and `false` clears a default. Relative paths resolve against the plist's folder. `library-root` puts the machines in another library; `-l` on the command line overrides it.
-
-```xml
-<dict>
- <key>version</key> <integer>1</integer>
- <key>defaults</key>
- <dict>
- <key>library-root</key> <string>~/vphone-lab</string>
- <key>iphone-version</key> <string>26.1</string>
- <key>preset</key> <string>presets/lab.plist</string>
- <key>cpu</key> <integer>4</integer>
- </dict>
- <key>machines</key>
- <array>
- <dict><key>name</key> <string>ci-1</string></dict>
- <dict><key>name</key> <string>ci-2</string></dict>
- <dict>
- <key>name</key> <string>fuzz</string>
- <key>iphone-build</key> <string>23F77</string>
- <key>iphone-version</key> <false/>
- <key>no-template</key> <true/>
- </dict>
- </array>
-</dict>
-```
-
-Every machine must name its firmware (`iphone-version`, `iphone-build`, or `iphone-source` with `cloudos-source`) or a `template`, so nothing prompts. All machines are checked as `vm create` checks them before the first is made, and `--dry-run` prints each one's `vm create` command. A name that exists is an error. `--skip-existing` skips it, so a run that stopped can be run again for the rest; a machine that failed is left as it stopped, so delete it first or it is skipped too. `--force-override` deletes that VM just before its machine is created, and refuses one that is running or a folder that is not a VM. Machines are created in order, so those with one template key clone the template the first one built, and the first failure stops the run. Run it with `sudo` when a machine needs a build, as `vm create`.
diff --git a/Documents/Guides/network-addresses.md b/Documents/Guides/network-addresses.md
deleted file mode 100644
index 6ca6eab0..00000000
--- a/Documents/Guides/network-addresses.md
+++ /dev/null
@@ -1,97 +0,0 @@
-# MAC and IP addresses
-
-[Documentation](../README.md) · [Networking](networking.md) · [Port forwarding](network-port-forwarding.md) · [Machines reaching each other](network-peers.md)
-
-## MAC address
-
-The first launch gives the guest's network card a random, locally administered
-MAC address and saves it in `config.plist`, the way it saves the machine
-identifier. The guest then keeps one identity, and one DHCP lease, across
-launches. To set or replace it:
-
-```sh
-vphone-cli vm config <name> --mac 02:11:22:33:44:55
-vphone-cli vm config <name> --mac random # a new one now
-vphone-cli vm config <name> --mac auto # a new one at the next launch
-```
-
-A cloned machine keeps the MAC of the original, like its machine identifier.
-Clone with `vm clone --new-identity` to give the copy new ones, or give it a
-new MAC before running both at once. `--new-identity` also clears the copy's
-fixed address, port forwards and mDNS name.
-
-## Addresses held by old MACs
-
-In `nat` mode the Mac's DHCP server keeps each address bound to the MAC it
-was given to, even after the lease runs out. It hands that address to anyone
-else only once every other address in the range is taken. Deleting a machine
-or replacing its MAC leaves its address bound to a MAC nothing uses any more,
-and so does every launch made before MACs were saved. New guests then get
-higher and higher addresses, until they reach the fixed addresses picked high
-in the range.
-
-`vm leases` lists the leases on the shared network and who owns each. It
-needs `VPhone.bundle` 2.5 or later:
-
-```sh
-vphone-cli vm leases
-sudo vphone-cli vm leases --release-orphans
-```
-
-An orphan is an iOS or iPadOS guest's lease whose MAC belongs to no machine in
-the library and whose lease has run out. `--release-orphans` removes the
-orphans from `/var/db/dhcpd_leases` and has the DHCP server read the file
-again, so it needs root. It never touches:
-
-- a machine's own lease, even one that ran out while the machine was stopped;
-- a lease that has not run out, such as a running guest's whose MAC was just
- replaced;
-- leases of other VM apps, or of devices on Internet Sharing.
-
-Machines in another library count only when that library is named too:
-repeat `--library-root` for each. The release refuses to run when a library
-has no machines or a machine's settings cannot be read, since every lease
-there would look orphaned.
-
-In Launchpad, Host Setup shows the count under NAT Network, and Release…
-frees them after an administrator approves. It compares against every
-library Launchpad lists. From the command line:
-
-```sh
-vphone-launchpad-cli vm leases
-vphone-launchpad-cli vm leases --release
-```
-
-## Fixed address
-
-`--ip` gives the guest a fixed IPv4 address. Without a prefix, `/24` is
-assumed. `--gateway` and `--dns` are optional; `auto` returns them to the
-default, and `--ip dhcp` removes the fixed address.
-
-```sh
-vphone-cli vm config <name> --ip 192.168.65.50
-vphone-cli vm config <name> --network tunnel --ip 10.20.0.5/16 --dns 1.1.1.1
-vphone-cli vm config <name> --ip dhcp
-```
-
-How the address reaches the guest depends on the mode:
-
-| Mode | Address | How it is applied |
-| --- | --- | --- |
-| `nat` | On the Mac's shared NAT network: normally `192.168.65.0/24`, or `192.168.64.0/24` for a machine with `--nat-peers off` ([Machines reaching each other](network-peers.md)) | vphoned writes it into the guest's network settings. The gateway and DNS are the Mac, `192.168.65.1` or `192.168.64.1`. |
-| `tunnel` | Any private subnet | The tunnel's own DHCP hands it out. The gateway, which is also the DNS resolver, is the subnet's first address unless `--gateway` names another. |
-| `bridged` | An address on the physical network | vphoned writes it into the guest. Set `--gateway` and `--dns` to the network's own. |
-
-In `nat` mode the address has to be on the shared network the machine joins:
-the second one for machines that reach each other, the default, or the first
-with `--nat-peers off`. Both follow vmnet's `Shared_Net_Address` if it has been
-moved. For any other subnet, use `tunnel`. macOS 26 can give a VM a NAT network of its own, but the
-subnet then stays reserved after the VM stops (still so 40 minutes later in
-testing), and every launch on it fails meanwhile, so vphone does not use it.
-
-vphoned applies the address each time `vphone-vm` connects to it, so a guest
-changed while the Mac was not looking is put back. It only ever undoes its own
-setting: an address typed into the guest's Settings app is left alone when the
-VM goes back to DHCP. An address on the shared `nat` network is not reserved in
-the Mac's DHCP server, so pick one high in the range, such as `.200`, that DHCP
-is unlikely to have handed to another VM.
diff --git a/Documents/Guides/network-names.md b/Documents/Guides/network-names.md
deleted file mode 100644
index fd3e7f51..00000000
--- a/Documents/Guides/network-names.md
+++ /dev/null
@@ -1,79 +0,0 @@
-# Names on the network
-
-[Documentation](../README.md) · [Networking](networking.md) · [Addresses](network-addresses.md) · [Tunnel mode](network-tunnel.md)
-
-## Name on the local network (mDNS)
-
-Off by default. `--mdns on` makes the guest answer to `<vm-name>.local`, with
-anything but letters and digits in the VM name turned into hyphens
-(`ipad_pro.13` becomes `ipad-pro-13.local`). `--mdns <name>` picks another
-name, and `--mdns off` puts the guest's own name back.
-
-```sh
-vphone-cli vm config <name> --mdns on
-ping <vm-name>.local
-```
-
-vphoned sets the name in the guest's network settings (`LocalHostName`) each
-time `vphone-vm` connects, and the guest's mDNSResponder announces it on every
-link it has. Besides its network card, a guest has the network link a USB-connected
-iPhone gives the Mac, which shows up on the Mac as an `en` interface with a
-`169.254` address. So the name works in
-every mode, `none` included:
-
-| Mode | `<name>.local` resolves to |
-| --- | --- |
-| `nat` | The guest's address on the shared network, and its USB link address |
-| `bridged` | The guest's LAN address, for every device on the LAN, and its USB link address on the Mac |
-| `tunnel`, `none` | The guest's USB link address, on the Mac only |
-
-The USB link address is link-local, but the Mac reaches the guest on it
-directly, so in `tunnel` mode a connection to `<name>.local` reaches a guest
-service without a port forward.
-
-If another device already uses the name, mDNS renames the guest (`name-2`).
-Renaming the VM with `vm rename` renames a name `--mdns on` derived from it;
-one picked by hand stays. A VM stopped with `vm stop` or by closing its window
-cannot withdraw its announcement, so the Mac's resolver keeps returning the
-old address until the cached record expires, which for a host address is 75
-minutes (TTL 4500 s).
-
-## This Mac's name in the guest
-
-On by default. The guest resolves this Mac's mDNS name (`scutil --get
-LocalHostName`, plus `.local`) at once, to the address it reaches the Mac at:
-
-| Mode | `<Mac>.local` in the guest |
-| --- | --- |
-| `nat` | The Mac on the shared network, usually `192.168.65.1` (`192.168.64.1` with `--nat-peers off`) |
-| `tunnel` | The gateway, `192.168.127.1` by default. Connections to it reach the Mac's loopback (`127.0.0.1`), the way `10.0.2.2` does in QEMU and VirtualBox |
-| `bridged` | The Mac's address on the bridged interface |
-
-Over mDNS alone, an IPv4 lookup of the Mac's name in the guest could fail. The
-guest also hears the Mac on the network link a USB-connected iPhone gives the
-Mac, where the Mac has no IPv4 address and answers "no such record". Whichever
-link answers first decides the lookup, so an app that wants an IPv4 address
-got an error until a real answer had been cached from another link.
-
-vphoned registers the name with the guest's own mDNSResponder the way it
-holds an `/etc/hosts` line: as a local record that answers an IPv4 lookup at
-once, with that one address, without asking the network and without the
-answers it has cached. It does so each time `vphone-vm` connects, and again
-when vphoned starts, so the name is in place before apps run after a reboot.
-The guest's system volume is read-only, so `/etc/hosts` itself is not edited,
-and nothing is announced on any network. IPv6 lookups still go to mDNS.
-
-Without it, a lookup also listed the Mac's `169.254` address on the USB link,
-first. iOS routes `169.254.0.0/16` through its primary interface, so a plain
-socket connecting to that address could leave through `en0`, where nothing
-answers, and wait out its timeout.
-
-```sh
-vphone-cli vm config <name> --mac-name off # withdraw it
-```
-
-To see what the guest's resolver returns, and whether each address connects:
-
-```sh
-vphone-launchpad-cli guest rpc <name> network.resolve '{"host":"<Mac>.local","family":"ipv4","port":8000}'
-```
diff --git a/Documents/Guides/network-peers.md b/Documents/Guides/network-peers.md
deleted file mode 100644
index ae3c9f7d..00000000
--- a/Documents/Guides/network-peers.md
+++ /dev/null
@@ -1,26 +0,0 @@
-# Machines reaching each other
-
-[Documentation](../README.md) · [Networking](networking.md) · [Addresses](network-addresses.md) · [Names on the network](network-names.md)
-
-In `nat`, Virtualization.framework isolates each guest from the others on the
-Mac's shared network by default: a guest reaches the Mac and the internet, not
-another VM. vphone turns that isolation off, so `nat` machines reach each other
-directly, Bonjour included. A virtual Apple Watch pairs with a virtual iPhone
-this way. A machine that should stay apart opts out:
-
-```sh
-vphone-cli vm config <name> --nat-peers off # isolate this guest again
-vphone-cli vm config <name> --nat-peers on # the default
-```
-
-In Launchpad it is "Reach other NAT machines" in the machine's Network
-settings. It applies from the next launch.
-
-vmnet puts the machines that reach each other on a second shared network, the
-block after the first: 192.168.65.0/24 beside 192.168.64.0/24, with the Mac at
-192.168.65.1. A fixed address (`--ip`) goes on that network; a machine whose
-fixed address is on the first network keeps its isolation unless it asks for
-its peers, and then needs an address on the second one. Isolation is a setting of each
-machine's own attachment, so a machine that opts out keeps vmnet's isolation
-whatever the others do. The switch is private to Virtualization.framework; a
-version without it leaves every guest isolated and says so when the VM starts.
diff --git a/Documents/Guides/network-port-forwarding.md b/Documents/Guides/network-port-forwarding.md
deleted file mode 100644
index da32113c..00000000
--- a/Documents/Guides/network-port-forwarding.md
+++ /dev/null
@@ -1,22 +0,0 @@
-# Port forwarding
-
-[Documentation](../README.md) · [Networking](networking.md) · [Addresses](network-addresses.md) · [Tunnel mode](network-tunnel.md)
-
-`--forward` carries a port on the Mac into the guest, in `nat` and `tunnel`
-modes. The form is `[tcp|udp:][host-address:]host-port:guest-port`. A forward
-listens on `127.0.0.1` unless a host address is given; `0.0.0.0` makes it
-reachable from other devices on the LAN.
-
-```sh
-vphone-cli vm config <name> --forward tcp:8022:22
-vphone-cli vm config <name> --forward udp:0.0.0.0:5353:53
-vphone-cli vm config <name> --remove-forward 8022
-vphone-cli vm config <name> --clear-forwards
-```
-
-`vphone-vm` opens the listeners when the VM starts and closes them when it
-stops. In `nat` mode it connects to the guest's address: the fixed one, or the
-one vphoned reports. In `tunnel` mode the connection reaches the guest as if it
-came from the gateway. A port that is already taken on the Mac is reported in
-the VM's log and skipped; the rest still work. `bridged` puts the guest on the
-LAN with its own address, so it needs no forwards.
diff --git a/Documents/Guides/network-tunnel.md b/Documents/Guides/network-tunnel.md
deleted file mode 100644
index a2daf5ed..00000000
--- a/Documents/Guides/network-tunnel.md
+++ /dev/null
@@ -1,64 +0,0 @@
-# Tunnel mode
-
-[Documentation](../README.md) · [Networking](networking.md) · [Addresses](network-addresses.md) · [Port forwarding](network-port-forwarding.md)
-
-## Why it exists
-
-`nat` and `bridged` send the guest's packets out through a physical interface.
-When a VPN owns the Mac's default route (WireGuard, Cloudflare WARP, or a proxy
-app in TUN mode such as Surge or Clash), those packets skip the VPN. They leave
-unencrypted, or not at all.
-
-In `tunnel` mode the guest's network card is implemented inside `vphone-vm`.
-It answers DHCP, ARP and ping for the gateway, and turns each guest TCP
-connection and UDP flow into a normal socket on the Mac. Those sockets follow
-the Mac's routing table like any other app's, so the VPN carries them. It needs
-no root, no new network interface and no change to the Mac's network settings.
-
-In a proxy app the guest shows up as its own client, named after the machine,
-and the app's rules apply to it as they would to any other app.
-
-## What the guest sees
-
-| Item | Value |
-| --- | --- |
-| Guest address | `192.168.127.3/24` by DHCP, or the [fixed address](network-addresses.md#fixed-address) |
-| Gateway and DNS | `192.168.127.1`, or the first address of the fixed address's subnet |
-| MTU | 1500 |
-| DNS | Queries to `192.168.127.1` go to the Mac's resolver |
-| Other connections to the gateway | The Mac's loopback, `127.0.0.1` (TCP and UDP) |
-
-## Limits
-
-- **IPv4 only.** The guest gets no IPv6 address, and IPv6 traffic is dropped.
-- **Outbound only, apart from forwarded ports.** Nothing on the Mac or the LAN
- can reach the guest through this network except the ports listed under
- [Port forwarding](network-port-forwarding.md). USB access (`iproxy`, `ideviceinstaller`)
- and `vphone.sock` do not use the guest network, so they still work.
-- **Ping reaches the gateway only.** ICMP to the internet is not forwarded,
- so `ping 1.1.1.1` in the guest fails even while TCP and UDP work.
-- **Throughput is limited by `vphone-vm`.** Every packet is handled in this
- process. Downloads and video work, but `nat` is faster when no VPN is involved.
-
-## Checking it works
-
-1. Start the machine and wait for it to finish booting.
-2. Read the guest's address:
-
- ```sh
- vphone-launchpad-cli guest rpc <name> device.network
- ```
-
- `en0` should show `192.168.127.3`. If it shows only an `fe80::` address,
- DHCP has not finished yet. Wait a few seconds and try again.
-3. Open a page in the guest:
-
- ```sh
- vphone-launchpad-cli guest rpc <name> apps.open_url '{"url":"https://example.com"}'
- ```
-
-4. On the Mac, the connections belong to `vphone-vm` and use the VPN's address:
-
- ```sh
- lsof -nP -a -i -p "$(pgrep -f 'vphone-vm.*<name>')"
- ```
diff --git a/Documents/Guides/networking.md b/Documents/Guides/networking.md
deleted file mode 100644
index eb59893f..00000000
--- a/Documents/Guides/networking.md
+++ /dev/null
@@ -1,59 +0,0 @@
-# Networking
-
-[Documentation](../README.md) · [Create a VM](create-and-run.md) · [Troubleshooting](troubleshooting.md)
-
-Each VM has one network mode, stored in its `config.plist`. It is read when the
-VM starts, so a change applies from the next launch.
-
-| Mode | How the guest reaches the internet | Use it when |
-| --- | --- | --- |
-| `nat` | Virtualization.framework's built-in NAT | The default. The Mac has no VPN, or the VPN does not need to carry the guest. |
-| `bridged` | Directly on a physical interface of the Mac, with its own address on that network | The guest has to be reachable from other machines on the LAN. |
-| [`tunnel`](network-tunnel.md) | Through ordinary connections opened by `vphone-vm` on the Mac | The Mac's traffic goes through a VPN or a proxy app, and the guest's traffic must follow it. |
-| `none` | No network device | The guest must stay offline. |
-
-## Choosing a mode
-
-In Launchpad, stop the machine, then choose Settings… from the `⋯` menu or the
-right-click menu. The Network section has a Mode picker. New Machine sets the mode under
-Advanced Options.
-
-From the command line:
-
-```sh
-vphone-cli vm config <name> --network tunnel
-# or through Launchpad
-vphone-launchpad-cli exec vm config <name> --network tunnel
-```
-
-`tunnel` needs a `VPhone.bundle` that lists it in `vphone-cli vm config --help`.
-An older bundle rejects the setting.
-
-## Unplugging a running VM
-
-`vm network` acts on a VM that is running, and nothing it does is saved:
-
-```sh
-vphone-cli vm network <name> # state of the NIC
-vphone-cli vm network <name> --link down # unplug the cable
-vphone-cli vm network <name> --link up # plug it back in
-```
-
-The guest sees the link drop and come back. The same is available on
-`vphone.sock` as `{"t":"network"}`, with `"link":"down"` or `"link":"up"`.
-
-A running VM cannot move to another network. Virtualization accepts the
-change and then stops the VM with an internal error, so `vm network` only ever
-puts back the network the VM started on. Change the mode with `vm config` and
-restart.
-
-In Launchpad, Settings… has Address and Port Forwarding sections when one
-machine is selected.
-
-## Further reading
-
-- [Tunnel mode](network-tunnel.md): why it exists, what the guest sees, its limits, and how to check it works.
-- [MAC and IP addresses](network-addresses.md): the saved MAC address, leases held by old MACs, and fixed addresses.
-- [Port forwarding](network-port-forwarding.md): carry a port on the Mac into the guest.
-- [Names on the network](network-names.md): the guest's `.local` name, and this Mac's name in the guest.
-- [Machines reaching each other](network-peers.md): `nat` machines on one shared network.
diff --git a/Documents/Guides/package-environment.md b/Documents/Guides/package-environment.md
deleted file mode 100644
index 1da57fa8..00000000
--- a/Documents/Guides/package-environment.md
+++ /dev/null
@@ -1,24 +0,0 @@
-# Package Environment
-
-The VM has no package manager by default. To install one:
-
-1. In the menu bar, choose **Apps > Install Bootstrap…** and select the **roothide** layout (**rootless** is deprecated). This installs Irisin in the VM.
-2. In Irisin, open the **OwnGoal Packages** repository, find **OwnGoal Bootstrap for vphone** (`owngoal-bootstrap-vphone`), and install it with **Bootstrap Install**.
-
- This one package brings in everything a VM needs in a single pass: `apt` and `dpkg`, `bash`, `zsh` and `dash`, `sudo`, the core command-line tools, `openssh-server`, `curl`, `wget`, `vim`, `git`, `uikittools`, `launchctl`, and the OwnGoal apps. Do not install these packages one by one: several depend on one another, and `openssh-server` declares some dependencies circularly, so separate installs can fail partway.
-3. After the first installation, install further packages normally.
-
-`vphone-cli vm create <name> --bootstrap roothide` does steps 1 and 2 during the new machine's first boot: it installs Irisin, then `owngoal-bootstrap-vphone` with Bootstrap Install through `irisin-cli`, from the repositories Irisin recommends. Step 2 needs an Irisin whose `irisin-cli install` has `--repository` and `--bootstrap-install`.
-
-If the first installation fails, do not repair it in place. Choose **Apps > Uninstall Bootstrap…**, then start again from step 1.
-
-## Remove the Environment
-
-Choose **Apps > Uninstall Bootstrap…**. The VM restarts after removal.
-
-Irisin keeps its data (downloads, journal, settings) in `Documents/wiki.qaq.irisin` under its home. On **roothide** that home is the environment's own `/var/mobile`, so uninstalling removes the data with everything else. On **rootless** it is the system's `/var/mobile`, and the data stays.
-
-Hold Option while opening the **Apps** menu to see two more options:
-
-- **Install Bootstrap from File…:** Installs from a local Irisin `.deb`.
-- **Uninstall Bootstrap Without Restarting…:** Removes the environment without restarting the VM.
diff --git a/Documents/Guides/shader-cache.md b/Documents/Guides/shader-cache.md
deleted file mode 100644
index 143bc225..00000000
--- a/Documents/Guides/shader-cache.md
+++ /dev/null
@@ -1,53 +0,0 @@
-# Persistent shader caches
-
-New VMs created with the Standard preset automatically enable the Task3 kernel
-patch and guest Metal cache reuse. The host saves its cache in
-`<machine>/ShaderCache`, for example `~/.vphone/machines/Lychee/ShaderCache`.
-Animations can lag while shaders compile on the first runs; later boots reuse
-the compiled shaders. A changed executable gets a new host cache identity.
-
-## Existing VMs
-
-Install a Core Bundle containing this feature and bind the stopped VM to it.
-In Launchpad, use **Update Guest Environment** from the machine's actions menu,
-then **Update Kernel** in its **Patches** inspector. Standard now selects
-**GPU Task3 shader cache** automatically. An explicit per-VM opt-out is preserved;
-enable that patch in the editor first if it was unchecked.
-
-The equivalent Launchpad CLI sequence is:
-
-```sh
-# Replace <version> with the installed Core Bundle version from bundle list.
-vphone-launchpad-cli vm stop Lychee
-vphone-launchpad-cli vm set-bundle Lychee <version> --update-environment
-vphone-launchpad-cli cfw update-kernel Lychee
-vphone-launchpad-cli vm start Lychee --wait
-```
-
-`--update-environment` redeploys the guest libraries and cache-reuse marker.
-`cfw update-kernel` re-patches the pristine kernel in `FirmwareOriginals` using
-the current selection and replaces the kernelcache in Preboot. Both updates
-keep the guest's data; no restore or `fw patch` is needed. Updating the Core
-Bundle binding alone does not update the installed kernel.
-
-Older VMs that have no pristine kernel in `FirmwareOriginals` need `fw prepare`
-and `fw patch` with the new bundle first, so the fallback restore tree contains
-the updated kernel. Then run `cfw update-kernel`; do not run `restore`.
-
-Standalone CLI users run the new bundle's `vphone-cli cfw update-environment
-Lychee` and `vphone-cli cfw update-kernel Lychee` with root authorization while
-the VM is off. Use `vphone-cli fw patches Lychee` to inspect pending patches.
-Both update commands apply the VM's current selection, including any other
-pending guest or kernel changes.
-
-## Resetting the host cache
-
-Stop the VM, then delete its `ShaderCache` directory. The next launch starts a
-fresh host cache. Guest Metal caches are separate files inside `Disk.img`, so
-clearing the host cache does not necessarily reproduce all first-run lag.
-
-Task3 applies to cloudOS 26.4 kernels only and is disabled in the tvOS presets.
-On a host older than macOS 27 the guest negotiates the host's own maximum version
-and keeps that version's features, so the host cache stays per-boot there.
-Runtime validation covered macOS 27.0.1, cloudOS 26.4, and iOS 27.0.1 and 26.6.2
-guests; older hosts were checked from their framework code, not run.
diff --git a/Documents/Guides/sharing-disk-space.md b/Documents/Guides/sharing-disk-space.md
deleted file mode 100644
index f01828c3..00000000
--- a/Documents/Guides/sharing-disk-space.md
+++ /dev/null
@@ -1,19 +0,0 @@
-# Sharing disk space between VMs
-
-[Documentation](../README.md) · [Library and backups](library-and-backups.md) · [Templates](templates.md)
-
-Two VMs restored separately from the same IPSW share nothing on disk, although much of their disk images is the same: two iOS 27.0 iPhones hold about 8.6 GB of identical bytes at the same places in their roughly 20 GB of data, mostly the system volume. `vm rebase` makes a stopped VM store those blocks once with another VM's, or with a template's:
-
-```sh
-vphone-cli vm rebase second --onto first --dry-run
-vphone-cli vm rebase second --onto 3f2a91c0d4e7
-```
-
-It rebuilds `second`'s disk image from an APFS clone of the base's and writes in only the blocks that differ. `--onto` takes a VM name or a template identifier (or a unique prefix of one) from `vm template list`; a VM wins when a name matches both. Every byte is compared with the original before the image is replaced, so the guest sees exactly the same disk. Only the disk image changes: `SEPStorage`, `nvram.bin`, `config.plist` and the device identity stay as they are. Rebasing onto a template leaves the template as it is, and the VM does not become one of its clones: `vm template show` does not list it. Both must be stopped and on the same APFS volume, and the volume needs free space for the blocks that are written until the old image is released. `--dry-run` reports what would be shared and written without writing anything.
-
-The saving is the **newly shared** figure. Bytes that are identical but already the same blocks on disk are reported as **already shared**, and rebasing them frees nothing. VMs made by `vm create` from one template already share its blocks, so rebasing one onto another, or onto that template, frees little; the command says so before it compares and again when the saving is under 0.1 GB. The VMs worth rebasing are ones restored without a template (`--no-template`) or imported.
-
-- The space comes back only when nothing else holds the old image's blocks. Snapshots of the VM, and clones made from it, keep them; delete those first or expect no saving.
-- `du` and Finder still count each image at its full size. Free space on the volume (`df`) is the honest measure.
-- The two images drift apart again as either VM writes to its disk. A base that is never booted, such as a template, stays the best base, and rebasing again later recovers what drifted.
-- A rebase that is interrupted leaves the VM unchanged and may leave a hidden `.rebase-*` folder in it; delete that folder.
diff --git a/Documents/Guides/snapshots.md b/Documents/Guides/snapshots.md
deleted file mode 100644
index 05bc69a3..00000000
--- a/Documents/Guides/snapshots.md
+++ /dev/null
@@ -1,85 +0,0 @@
-# Snapshots
-
-[Documentation](../README.md) · [Create a VM](create-and-run.md) · [Troubleshooting](troubleshooting.md)
-
-A snapshot saves a stopped VM's disk and boot state so you can return to it
-later: take one after a clean install, try something destructive in the guest,
-then revert.
-
-```sh
-vphone-cli vm snapshot create myphone clean --note "fresh install"
-vphone-cli vm snapshot list myphone
-vphone-cli vm snapshot revert myphone clean
-vphone-cli vm snapshot delete myphone clean
-```
-
-`revert` and `delete` ask before they change anything; `--force` skips the
-question. A revert keeps the snapshot, so you can go back to it again.
-`list --json` prints an array of `{"name", "created", "note"}` objects, oldest
-first, with `created` in ISO 8601 and `note` left out when there is none.
-
-## Stop the VM first
-
-`create` and `revert` refuse while the VM is running, and so does anything that
-holds its disk image, `SEPStorage` or `nvram.bin` open. Stop it with
-`vphone-cli vm stop myphone` or from its window, then try again. The refusal
-names each process holding them; when none of them runs the VM (a backup tool,
-Spotlight), it says so, and the retry succeeds once that process closes them.
-
-The three files move together. The Secure Enclave's anti-replay counters live in
-`SEPStorage`, and the disk holds the matching state. A disk from one moment with
-a `SEPStorage` from another makes the SEP panic on the next boot, so a snapshot
-always takes all three at once and a revert always puts all three back.
-
-A revert is all or nothing. If it fails partway, it puts the VM's own files
-back and reports the error, so the VM is as it was. In the rare case that
-putting them back fails too, the error says so: revert to a snapshot again
-before starting the VM. A snapshot whose `Snapshot.plist` does not list all
-three files, or lists a file that is not part of a snapshot, is refused as
-damaged before anything changes.
-
-`list` and `delete` work while the VM runs; neither touches its live files.
-
-## What a snapshot holds
-
-| Captured | Why |
-| --- | --- |
-| The disk image (`Disk.img`) | The guest's system and data |
-| `SEPStorage`, `nvram.bin` | Secure Enclave state and the boot chain's NVRAM, which must match the disk |
-| `PatchReceipt.plist` | Which patches are live in the guest |
-| `restore-info.json` | The iOS version on the disk, and whether `cfw install` finished |
-
-The last two are taken when present. If one did not exist when the snapshot was
-taken, a revert removes it, so the records describe the restored disk rather
-than a later install.
-
-Not captured, and unchanged by a revert:
-
-- `config.plist`: the device identity, CPU, memory, network and other settings.
- Change them with `vm config` whenever you like; a revert does not undo that.
-- Patch choices (`PatchSelection.plist`), the restore tree, `FirmwareOriginals/`
- and the ROMs. These are inputs on the Mac, not guest state.
-- `launchpad.json`. Launchpad saves its own copy in the snapshot folder and puts
- it back itself. The CLI keeps any extra file in a snapshot folder untouched and
- deletes it with the snapshot.
-
-## Disk space
-
-Snapshots live in `<vm>/Snapshots/<name>/` as APFS clones. Taking one is instant
-and costs no space; the VM and its snapshots share every block until the guest
-writes to it, and then only the changed blocks take new space. Because of this,
-`du` and Finder count each snapshot at the full size of the disk and overstate
-what it really uses. Free space on the volume is the honest measure.
-
-A snapshot keeps the disk blocks it was taken with. `vm rebase`, which makes a
-VM share identical blocks with another VM's, frees nothing while a snapshot of
-that VM still holds the old ones; see
-[Sharing disk space between VMs](sharing-disk-space.md).
-
-The VM must be on an APFS volume. Elsewhere `create` refuses rather than copying
-a disk image that can be tens of gigabytes.
-
-## Clones and exports
-
-`vm clone` and `vm export` leave snapshots behind: a clone or an imported VM
-starts with none. Deleting or renaming a VM takes its snapshots with it.
diff --git a/Documents/Guides/template-building.md b/Documents/Guides/template-building.md
deleted file mode 100644
index a0bd92d1..00000000
--- a/Documents/Guides/template-building.md
+++ /dev/null
@@ -1,47 +0,0 @@
-# Building and finding templates
-
-[Documentation](../README.md) · [Templates](templates.md) · [Create and Run](create-and-run.md)
-
-## Finishing a VM as a template
-
-To turn a VM straight after creating it into a template, stop it, trim it, give it the setup boot, and adopt it. This is what Launchpad does for a template it has to build (below):
-
-```sh
-vphone-cli vm stop phone-src
-vphone-cli vm template trim phone-src --tier standard # offline, no root; frees nothing until the setup boot
-vphone-cli vm template setup phone-src # headless; --window to watch, slimming switches as for vm create
-vphone-cli vm template adopt phone-src --iphone-source … --cloudos-source … # key from its records; the sources are recorded
-vphone-cli vm create phone-d --template <id> --skip-first-boot
-```
-
-`--iphone-source` and `--cloudos-source` on `vm template adopt` record the IPSWs the VM was created from in its `Template.plist`, as a `vm create` that builds a template does. `--json` prints the new template as `vm template show --json` does.
-
-`--expect <id>` on `vm template adopt` refuses, and leaves the VM where it is, unless its records give the template identifier `<id>`: the `id` that `vm template find` printed for the options the VM was built with. Without the check, a VM whose setup boot fell short (an app it could not remove) would be saved under another key, and every later `vm create` with those options would miss it and build another template. The refusal names the fields that differ when it can work out the expected key, which it can when a template or build in the library has it or when only the slimming differs; otherwise it prints the VM's own key to compare. With `--json` the refusal is also printed to stdout as `{"adopted": false, "error": "unexpected_template", "id": …, "expected": …, "differences": […], …}`, and the command exits with status 1.
-
-`vm template setup` refuses a running VM and a frozen template. It trims nothing itself: the tier `vm template trim` recorded is kept, and a `--trim` that names another tier is refused. On a VM it reports an app vphoned would not remove and leaves it out of the recorded steps, so the adopted key says what was really done. With `--strict` it fails instead, records nothing, and the setup boot can be run again: use it when the VM is to be adopted with `--expect` under the key `vm template find` gave for the same switches. Given a `.building-…` name from `vm template list` (a `vm create` whose setup boot failed), it sets the build up to its key, which fixes the slimming, runs the offline trim first if the build stopped before it, and freezes it on success.
-
-## Finding a template
-
-`vm template find` answers what template a `vm create` with the same options would clone from, without downloading, restoring or changing anything:
-
-```sh
-vphone-cli vm template find --iphone-source … --cloudos-source … [--device …] [--preset …] [--disk-size …] [--block <id>] [--allow <id>] [slimming switches] --json
-```
-
-It works out the key as `vm create` does. The builds come from the IPSWs when they are local files or already in the IPSW cache, and otherwise from a template whose record names the same two sources, so the key still resolves once the IPSWs were deleted, local ones included. `--block` and `--allow` are per-patch overrides as `fw set-patches` records them. The JSON has `resolved`, `resolvedBy` (`ipsw` or `template`), `id`, `summary`, `key`, `template` (the matching template as `vm template show --json` prints it, current or stale), `usable` (it exists and is current), `building` (a create holds its build lock) and, when unresolved, `reason`.
-
-## In Launchpad
-
-Launchpad 2.9 creates machines from templates by default. New Machine opens on a short page: the name, the device and iOS version from the firmware catalog, and a Slim System switch. A row below it sums up the rest and opens Advanced Options, four pages for hardware; the template and its parts (the trim tier and kept languages, the service profile, and which system apps go); the Core Bundle, custom IPSWs and patches; and the location, network and restore options. The row counts the settings that differ from the defaults and names anything there that stops Create. Turning off Create from a template restores the machine on its own, as `--no-template` does, with keys of its own and without slimming. Apple Account is not offered: the guest refuses its sign-in either way, so Launchpad passes `--accounts-off` whenever the service profile is trimmed. The sheet grows with its page up to 600 points and scrolls past that, so its buttons stay on a laptop screen.
-
-Under Firmware, a release that also runs on its own cloudOS (`fw catalog`'s third column) offers that cloudOS beside the recommended one, with the `ipsw` that stages the kernelcache mix. The creation then stages the mix as you and has the helper link it as root, which asks for authorization once.
-
-The 2.12 Launchpad interface still shows its legacy ipsw selector for older compatible bundles. Native Core Bundle extraction ignores the selected tool path; the CLI no longer needs it.
-
-The iPhone XS Max runs iOS 18.1 to 18.7.2, each on its own release's cloudOS, with no template and the Minimal preset by default; Standard works as well (checked on 18.6). Its pairings always rebuild the kernelcache, so Firmware asks for the `ipsw`, and for the macOS builder: `user@host` of a Mac or macOS VM running macOS 15 or 26.0 to 26.3 with Remote Login on, and its password for ssh and sudo (empty with ssh keys and passwordless sudo). Launchpad keeps the builder like the `ipsw`, but not the password, which reaches `vphone-cli` only in its environment (`VPHONE_KMUTIL_SSH_PASSWORD`). The creation then stages and links the mix as you, over ssh; from macOS 26.4 on the builder is required, on an older Mac without one the helper links it as root.
-
-The creation runs `vm template find` first. When a current template matches, it clones the machine (`vm create --template <id> --skip-first-boot`) and boots it. When none does, it builds the template in a temporary machine of the same library, named `template-` and eight hex digits, with its usual steps (restore, then `cfw install` through the helper), then `vm template trim`, the headless `vm template setup --strict` and `vm template adopt --iphone-source … --cloudos-source … --expect <id>`, and clones the machine from the result. The setup boot fails when an app it should remove stays, and the adopt fails when the build's key comes out other than the one `find` computed, so a build is never saved under an id later creations would not find. Each is a step of its own with its duration, and a failed one shows the reason `vphone-cli` gave.
-
-Per-patch overrides from New Machine's Patch Settings are split the way the template key splits them. Boot-chain overrides are part of the key: the template is built with them, and `find` looks for one with them. Guest patch overrides are not: the template is built without them, and after the clone the creation records them on the new machine with `fw set-patches` and writes them with `cfw update-environment` through the helper (the Apply guest patches step) before its first boot. A template therefore never hands one creation's guest patch choice to another. Once it has built a template, the creation offers to delete the two IPSWs it came from; nothing is deleted without confirming.
-
-File > Templates… lists every library's templates with their machines, slimming, size and state, and deletes them. Guest System… (in a machine's Actions menu and inspector) switches a running machine's service profile and restores system apps the template removed. The inspector and the machine list show each machine's exclusive disk use beside what its files allocate: the blocks no other machine or template holds, which deleting it frees (a local Time Machine snapshot taken before keeps them until it expires).
diff --git a/Documents/Guides/templates.md b/Documents/Guides/templates.md
deleted file mode 100644
index 881d25f1..00000000
--- a/Documents/Guides/templates.md
+++ /dev/null
@@ -1,84 +0,0 @@
-# Templates
-
-[Documentation](../README.md) · [Create and Run](create-and-run.md) · [Building and finding templates](template-building.md) · [Library and backups](library-and-backups.md)
-
-A template is a complete machine kept in `<library>/.templates/<id>/`. It boots once while it is built, its setup boot, and never again once it is frozen. `vm create` without `--no-template` works out the template key from its options and the two IPSWs before anything is restored: the guest device, the iOS and cloudOS versions and builds, the patch preset and the boot-chain patches it resolves to (every patch it resolves to, guest ones included, for a preset the bundle does not ship: a preset file or one in `~/.vphone/patches_presets` can change under the same identifier, and a clone keeps its template's guest patches), the bundle series (`2.9` for 2.9.x), the disk size, what is trimmed from the guest's System volume (`--trim`), and the slimming switches below. Then:
-
-- If a template with that key exists, the VM is cloned from it with a new identity, given the requested CPU, memory and network, and booted once to check vphoned. This takes seconds and needs neither root nor the IPSWs; nothing is downloaded. The builds come from the IPSWs when they are local files or already in the IPSW cache, and otherwise from a template recorded with the same two sources, as [`vm template find`](template-building.md#finding-a-template) works them out; a local IPSW that has been deleted counts as not there.
-- Otherwise the IPSWs are downloaded if they are not there, and the full pipeline runs into a staging folder, `.templates/.building-<id>-<uuid>/`: `cfw install`, the offline trim, then the setup boot; the result is frozen and renamed to `.templates/<id>/` in one step, and the VM is cloned from it. The restore tree is removed before the freeze whatever `--keep-artifacts` says: a template never keeps it, because its ~11 GB would stay pinned for as long as the template lives and no clone can use it. `--keep-artifacts` keeps it only with `--no-template`, and `vm template adopt` removes it too. A second `vm create` with the same key waits for the first instead of restoring a second copy. A failed build stays in its staging folder for inspection.
-
-```sh
-vphone-cli vm create phone-a --iphone-source … --cloudos-source … # builds the template, clones phone-a
-vphone-cli vm create phone-b --iphone-source … --cloudos-source … # clones phone-b, no restore
-vphone-cli vm create phone-c --template 3f2a91c0d4e7 --cpu 4 --memory 6144
-```
-
-`--template <id>` clones from a template by its identifier (or a unique prefix of four or more digits) and takes no IPSW options. `--device`, `--preset`, `--disk-size` and the slimming switches, when given, must match the template's; a clone cannot change them. CPU, memory, screen and network are not part of the key.
-
-## Offline trim
-
-After `cfw install`, a template build deletes system files the guest never needs from its System volume, offline, with the volume mounted on the host. `--trim` on `vm create` (default `standard`) and `--tier` on `vm template trim` pick the tier:
-
-| Tier | Deletes | About |
-| --- | --- | --- |
-| `none` | nothing | |
-| `conservative` | the contents of `usr/standalone/update` (software-update ramdisk, baseband firmware) | 0.35 GB |
-| `standard` | conservative, plus the AirPods/Beats pairing assets (`PreinstalledAssetsV2/RequiredByOs/com_apple_MobileAsset_SharingDeviceAssets`), the watch faces (`NanoTimeKit/FaceBundles`) and the `LinguisticData/RequiredAssets_*.bundle` of every language not kept | 1.2 GB |
-| `aggressive` | reserved: refused until it has been validated on a guest | |
-
-`--keep-languages` (default `en,zh-Hans,zh`; English is always kept) chooses the languages standard keeps. The tier, the version of the list and the kept languages are part of the template key (`standard/1/en,zh,zh-Hans`), so templates trimmed differently never match. Trimming cannot be undone: a clone cannot get the files back.
-
-The deleted files free nothing at first. The guest's original system snapshot (`orig-fs.disabled.rn-*`, left by `cfw install`) still holds every block, and the host cannot delete it, even as root. The setup boot deletes it as its first step, and only then is the space returned. So a trim is refused for a template that gets no setup boot, and a trimmed template is frozen or adopted only once its snapshot is gone. `vm template trim` needs no root, runs on a stopped machine that has not been cloned from a template, or on an unfinished `.building-…` folder, and refuses a frozen template.
-
-## Setup boot and slimming
-
-The setup boot finishes the template the way every clone should start. It boots the template once and, through vphoned, in this order:
-
-1. deletes the `orig-fs.disabled.rn-*` APFS snapshot `cfw install` left (it holds about 20 MB, and every file trimmed from the System volume until it is gone);
-2. skips Setup Assistant (`setup.skip`);
-3. waits for first-boot work to settle (`setup.settle`, up to 10 minutes): installd expands the removable system apps on the first boot;
-4. removes the system apps (`apps.remove_system`, backups kept in the guest);
-5. applies the service profile (`services.profile.apply`), which includes turning off the sign-in follow-up daemons (`followupd`, `appleidsetupd`);
-6. reboots, then checks: no snapshot left, Setup done, none of the profile's services running, the removed apps gone, vphoned answering;
-7. clears the device name `vphone-vm` pinned for this boot, and shuts the guest down cleanly.
-
-Every step has a deadline. A failed step stops the VM, records nothing and leaves the build unfrozen; `vm create` names the step and how to retry it.
-
-| Switch | Default | Effect |
-| --- | --- | --- |
-| `--slim on\|off` | on | `off` trims nothing and keeps every app and service. The setup boot still runs: Setup is skipped and the snapshot deleted. |
-| `--trim none\|conservative\|standard` | standard | The offline trim above. |
-| `--keep-languages <list>` | `en,zh-Hans,zh` | The languages `--trim standard` keeps. |
-| `--service-profile trimmed\|none` | trimmed | vphoned's trimmed profile: about 140 launchd jobs off, the App Store daemons and sign-in follow-up among them. A phone with this profile cannot pair an Apple Watch (see `Research/Guest/watch_pairing.md`). |
-| `--remove-apps on\|off` | on | Removes App Store, Home, TV, News, FaceTime, iTunes Store, Messages, Games, Find My and Wallet. Camera and Phone stay. |
-| `--keep-apps <ids>` | none | Bundle IDs from that list to keep, comma-separated (`com.apple.findmy,com.apple.Passbook`). |
-| `--accounts-off` | off | Also turns off `akd`, `amsaccountsd` and `appleaccountd`. The guest then cannot sign in to an Apple Account. |
-
-Each choice is part of the key, so templates with different slimming live side by side and each serves only the creates that ask for it. Removed apps and the profile stay reversible on a clone: `apps.restore_system` puts an app back from its backup, and `services.profile.apply {"profile":"none"}` turns back on exactly what the profile turned off (both through `vphone-launchpad-cli guest rpc`, or Guest System in Launchpad).
-
-What every clone inherits from the template: Setup done, the apps and services as the setup boot left them, the first-boot work installd and the indexers did, and the Data volume as of that boot. It does not inherit a device name: the template's pin is cleared, so a clone shows `iPhone` until its own VM connects and pins the clone's name. A new identity also means the Mac asks "Trust This Computer?" again.
-
-To turn a VM into a template by hand, ask which template a `vm create` would use, or see how Launchpad builds them, read [Building and finding templates](template-building.md).
-
-## Shared secrets
-
-Every machine cloned from one template shares, with the template and with each other, its SEP root secret, its Data volume keys and the data the restore and the setup boot wrote. One clone could in principle decrypt another's Data volume. A VM that needs keys of its own, for example to sign in to Apple services for multi-device research, should be created with `--no-template` (which takes no slimming switches). Clones get a new ECID, UDID and MAC address on their first start, as with `vm clone --new-identity`, and share every unchanged block with the template on APFS: a new clone costs almost nothing until it starts writing, and a slimmed template leaves it little first-boot work to write.
-
-```sh
-vphone-cli vm template list # id, key summary, STALE with the reasons
-vphone-cli vm template show <id> --json
-vphone-cli vm template trim myphone --tier standard # trim a stopped VM before adopting it
-vphone-cli vm template setup myphone # the setup boot, on a stopped VM
-vphone-cli vm template adopt myphone # freeze a stopped, newly created VM into a template
-vphone-cli vm template delete <id>
-```
-
-- **Stale.** A template is listed as stale when this `vphone-cli` belongs to another bundle series, when its key has an older format, when its preset now resolves to other boot-chain patches, or when its patch receipt disagrees with its plan. A stale template is never used: `vm create` with its key fails and names it. Delete it to have the next `vm create` build a new one.
-- **Adopt.** `vm template adopt <vm>` turns a stopped VM into a template, under the key its own records give (`restore-info.json`, `PatchPlan.plist`, `config.plist`, the disk image, Launchpad's `launchpad.json`, and the steps `vm template trim` and `vm template setup` recorded in its `Template.plist`). The VM leaves `vm list`. Adopt a VM straight after its setup boot: every clone inherits what its guest has done since. A VM with snapshots is refused, and so is one that would be stale unless `--force` is given.
-- **Never booted once frozen.** `vm launch` and `vphone-vm` refuse a frozen template, in DFU too; no machine name reaches into `.templates`, so `vm launch`, `clone`, `export`, `rename` and `delete` cannot pick one up by accident. A template that booted after being frozen would write state into the blocks every later clone inherits, and the clones made before it would stop sharing them.
-- **Machines using it.** A machine cloned from a template records the template in `TemplateSource.plist`; a `vm clone` of it keeps the record (the copy shares the template's blocks too) and `vm export` leaves it out (an import shares nothing). The record also names the template's build, so a template deleted and built again with the same key does not count the machines cloned from the old one, which share none of its blocks. `vm template list` and `show` list the machines using each template and its size on disk, and `vm info` shows a machine's template. When `vm delete` removes the last machine cloned from a template that still exists, it says so, and never deletes the template itself:
-
- ```
- note: template 3f2a91c0d4e7 (~17.40 GB) is no longer used by any machine; remove it with `vphone-cli vm template delete 3f2a91c0d4e7`
- ```
-- **Deleting.** `vm template delete <id>` removes the template; machines cloned from it keep working. The blocks they still share with it are freed only when those machines change them or are deleted, so deleting a template frees less than its size while clones remain. The note it prints says which: the machines that use it, whose shared blocks stay allocated until they change them or are deleted, or that no machine uses it now, so deleting frees its blocks, though a local Time Machine snapshot taken while it existed may keep them until the snapshot expires. `--json` with `--force` prints the same facts. Templates take disk space although `vm list` does not show them; look in `~/.vphone/machines/.templates`, keeping in mind that `du` counts a template and each of its clones in full.
diff --git a/Documents/Guides/troubleshooting.md b/Documents/Guides/troubleshooting.md
deleted file mode 100644
index fd63660d..00000000
--- a/Documents/Guides/troubleshooting.md
+++ /dev/null
@@ -1,29 +0,0 @@
-# Troubleshooting
-
-[Documentation](../README.md) · [Host setup](host-setup.md) · [Create a VM](create-and-run.md)
-
-## `vphone-vm` is killed before the VM opens
-
-Run `vphone-cli host preflight`. The CLI is unentitled and can explain an AMFI refusal of its signed `vphone-vm` companion. If you rebuilt, the cdhash changed: allow the new binaries with the bundled helper as described in [host setup](host-setup.md).
-
-## `Virtualization is not available on this hardware`
-
-PV=3 guests cannot be nested. Boot on an Apple Silicon Mac rather than inside another macOS VM.
-
-## `vm create` printed vphoned success, but no VM is running
-
-That is expected. Creation starts a temporary GUI boot, sends a real ping, and stops that boot before returning. Start the VM for use with `vphone-cli vm launch <name>`.
-
-## Stuck at “Press home to continue”
-
-Click the Home button in the VM window's title bar. The current JB workflow does not install a VNC server.
-
-## App exits with `EXC_GUARD` / `GUARD_TYPE_MACH_PORT`
-
-The kernel patch `kernel-boot-thread_guard_violation` stops fatal Mach port guard delivery. It applies only on an iOS 18 base, where it is needed to boot, and every preset turns it on there. Other bases cannot select it, so an app that trips this guard on a 26.x base still exits. See [issue #291](https://github.com/Lakr233/vphone-cli/issues/291).
-
-## Restore or first boot fails
-
-Keep the VM in DFU until `restore` exits in a manual flow, and check that online ticket requests can reach Apple. For the complete pipeline, rerun `vm create` with a **new name** and `-v` for tool detail; avoid parallel VM creation when memory or disk is tight. Inspect [firmware compatibility](compatibility.md) before combining an iPhone IPSW with a PCC image.
-
-If the guest boots but vphoned does not answer, the first-boot check times out after 300 seconds. A GUI boot is used because a newly restored guest may not bring up vphoned during its first headless boot. See [create and run](create-and-run.md) for what the success marker proves.
diff --git a/Documents/README.md b/Documents/README.md
index b9216808..42c011f3 100644
--- a/Documents/README.md
+++ b/Documents/README.md
@@ -1,85 +1,14 @@
-# Documentation
+# vphone Documentation
-Start with the [Launchpad quick start](../README.md#get-started). For terminal use, see [Create and Run](Guides/create-and-run.md). There is one public firmware mode; a patch preset (Standard, Minimal and others) selects the patches, and `--block` or `--allow` adjusts single patches.
+Read it on the documentation site: **<https://lakr233.github.io/vphone-cli/>**
-## Get Started
+The site is built from this folder and from [`Research/`](../Research/README.md). Each language has the same tree:
-| Page | Use it for |
+| Language | Manual |
| --- | --- |
-| [Downloads](Downloads/README.md) | Notarized Launchpad versions and matching `VPhone.bundle` versions |
-| [Host Setup](Guides/host-setup.md) | Apple Silicon, SIP and AMFI settings, signing and preflight |
-| [Create and Run](Guides/create-and-run.md) | The one-command flow, starting and stopping a VM, manual stages |
-| [Compatibility](Guides/compatibility.md) | Verified firmware pairs and what the checks prove |
+| English | [en/README.md](en/README.md) |
+| 简体中文 | [zh/README.md](zh/README.md) |
+| 日本語 | [ja/README.md](ja/README.md) |
+| 한국어 | [ko/README.md](ko/README.md) |
-## Machines
-
-| Page | Use it for |
-| --- | --- |
-| [Firmware Preparation](Guides/firmware-preparation.md) | The GPU driver restore, kernelcache mixes for newer cloudOS, remote linking |
-| [Templates](Guides/templates.md) | How `vm create` reuses one restore, offline trim, setup boot and slimming |
-| [Building and Finding Templates](Guides/template-building.md) | Turning a VM into a template, `vm template find`, templates in Launchpad |
-| [Create Many Machines](Guides/many-machines.md) | `vm create-bulk` from a plist |
-| [Device Name and Clock](Guides/device-name-and-clock.md) | What the guest takes from the VM name and the Mac's clock |
-| [Library, Firmware and Backups](Guides/library-and-backups.md) | Where machines and caches live, downloads, clones and exports |
-| [Sharing Disk Space](Guides/sharing-disk-space.md) | `vm rebase` for VMs restored separately |
-| [Snapshots](Guides/snapshots.md) | Saving a stopped VM's disk state and reverting to it |
-| [Package Environment](Guides/package-environment.md) | Installing and removing a package manager in the VM |
-| [Persistent Shader Caches](Guides/shader-cache.md) | Enabling shader caches on an existing VM |
-
-## Devices
-
-| Page | Use it for |
-| --- | --- |
-| [Other iPhone Models](Guides/iphone-models.md) | Running iOS from an iPhone 16 Pro, 17, 17 Pro, Air or other model's IPSW |
-| [iPadOS Guests](Guides/ipados.md) | Running iPadOS from an iPad restore IPSW instead of iOS |
-
-## Networking
-
-| Page | Use it for |
-| --- | --- |
-| [Networking](Guides/networking.md) | Network modes, choosing one, unplugging a running VM |
-| [Tunnel Mode](Guides/network-tunnel.md) | A Mac behind a VPN or proxy app |
-| [MAC and IP Addresses](Guides/network-addresses.md) | The saved MAC, leases held by old MACs, fixed addresses |
-| [Port Forwarding](Guides/network-port-forwarding.md) | Carrying a port on the Mac into the guest |
-| [Names on the Network](Guides/network-names.md) | The guest's `.local` name and this Mac's name in the guest |
-| [Machines Reaching Each Other](Guides/network-peers.md) | `nat` machines on one shared network |
-
-## Reference
-
-| Page | Use it for |
-| --- | --- |
-| [Launchpad Command Line](Guides/launchpad-cli.md) | Driving Launchpad with `vphone-launchpad-cli` |
-| [Core Bundles and Local Builds](Guides/core-bundles.md) | Binding machines to bundles, installing and comparing local builds |
-| [Bundle Integration](Guides/bundle-integration.md) | What `VPhone.bundle` contains and how an app integrates it |
-
-## Help
-
-| Page | Use it for |
-| --- | --- |
-| [Troubleshooting](Guides/troubleshooting.md) | Launch refusals, restore failures, Home key and app problems |
-
-## Translations
-
-[中文](README_zh.md) · [日本語](README_ja.md) · [한국어](README_ko.md)
-
-These pages give a translated overview and quick start. The guides above hold the current procedures.
-
-## For Contributors
-
-- `vphone-launchpad`: A Mac app that downloads and installs `VPhone.bundle` and sets up the host. Released separately.
-- `vphone-cli`: Prepares firmware, patches it, restores the system, and manages VMs.
-- `vphone-vm`: Runs the VM and shows its window.
-- `vphoned`: The control service inside the VM. The window's features and the API work through it.
-
-| Path | Contents |
-| --- | --- |
-| [`VPhoneExecutable/`](../VPhoneExecutable/) | `vphone-cli`, `vphone-vm`, firmware patching and restore |
-| [`VPhoneKit/`](../VPhoneKit/) | Shared host libraries and API client |
-| [`VPhoneDaemon/`](../VPhoneDaemon/) | `vphoned` |
-| [`VPhoneGuestComponents/`](../VPhoneGuestComponents/) | Hooks and helper programs inside the VM |
-| [`VPhoneLaunchpad/`](../VPhoneLaunchpad/) | The Launchpad app and its helper |
-
-- `xcodebuild -workspace VPhone.xcworkspace -scheme VPhone build` produces and validates `VPhone.bundle`. Run each project's test scheme separately.
-- The [research index](../Research/README.md) groups patch and implementation records by subject.
-- [`VPhoneWebsite/`](../VPhoneWebsite/) builds the documentation site from these pages with Rspress: `npm ci && npm run dev` there. Every guide must be listed in a section above; the site's sidebar is built from them.
-- The [patch inventory](../Research/0_binary_patch_comparison.md) compares patches per component.
+English is the source. A change to an English page needs the same change in every translation. The [research notes](../Research/README.md) are English only.
diff --git a/Documents/README_ja.md b/Documents/README_ja.md
deleted file mode 100644
index dd330215..00000000
--- a/Documents/README_ja.md
+++ /dev/null
@@ -1,171 +0,0 @@
-<div align="right"><a href="../README.md">English</a> · <a href="README_zh.md">中文</a> · <strong>日本語</strong> · <a href="README_ko.md">한국어</a></div>
-
-# vphone-cli
-
-Apple Silicon Mac で仮想 iPhone を実行します。
-
-> [!WARNING]
-> 本プロジェクトは、暗号資産やトークンを発行したことも、その発行を許可したこともありません。また、暗号資産による支払いや寄付は受け付けていません。本プロジェクトの名をかたって発行・宣伝されるものや、本プロジェクトとの関係をうたう暗号資産・トークンは、すべて詐欺です。
-
-![macOS 上で動作する仮想 iPhone](demo.jpeg)
-
-vphone-cli は Apple の Virtualization.framework と PCC 研究用仮想マシンを使って iOS を実行します。セキュリティ研究、リバースエンジニアリング、デバッグに適しています。
-
-- **グラフィカルウィンドウ**:Mac 上で仮想 iPhone の画面を操作し、App とファイルを閲覧し、スクリーンショットの撮影や画面収録ができます。
-- **カスタムファームウェア(Custom Firmware)**:システムにはあらかじめパッチが適用されており、パッケージ環境をインストールできます。
-- **バックアップと複製**:仮想マシンの書き出し、読み込み、複製ができます。
-- **自動化 API**:任意で有効にできる、ローカルの HTTP と WebSocket のインターフェースです。
-- **追加の依存なし**:実行時に Xcode、Python、Homebrew は不要です。
-
-## 準備
-
-- macOS 15 以降を搭載した物理 Apple Silicon Mac。macOS の仮想マシン上では使用できません。
-- 十分なディスク容量。仮想マシンごとに標準で 64 GB の仮想ディスクを使用し、ファームウェアと一時ファイルにも別途容量が必要です。
-- ネットワーク接続。システムの復元時に署名チケットをオンラインで取得します。
-- セキュリティ設定の変更。macOS 復旧モードに入り、ターミナルで次のコマンドを実行してから再起動します。
-
- ```sh
- csrutil enable --without debug
- csrutil allow-research-guests enable
- ```
-
- SIP は有効のまま、デバッグの制限だけを緩和します。理由と別の設定方法は[ホストの設定](Guides/host-setup.md)をご覧ください。
-
-## クイックスタート
-
-1. [最新のリリース](https://github.com/Lakr233/vphone-cli/releases/latest)から `vphone-launchpad-<バージョン>-notarized.zip` をダウンロードし、展開して開きます。すべてのリリースが公証済みではありません。最新リリースに `-notarized` ファイルがない場合は、[ダウンロードガイド](Downloads/README.md)から公証済みのバージョンを選んでください。
-2. **Host Setup** で開発者ツールへのアクセスを許可し、ヘルパーをインストールします。
-3. **Core Bundle** で **Download and Install** をクリックします。Launchpad が `VPhone.bundle` をダウンロードして検証し、その中の仮想マシン用プログラムがこの Mac で実行できるようにします。
-4. **Machines** で **New Machine** をクリックし、ファームウェアの組み合わせを選んで **Create** をクリックします。
-
-Launchpad がファームウェアのダウンロード、パッチの適用、システムの復元、初回起動を行います。完了後も仮想マシンは実行されたままです。
-
-自分の iPhone と cloudOS の IPSW を使うこともできます。検証済みの組み合わせは[互換性ガイド](Guides/compatibility.md)をご覧ください。
-
-### エージェントに任せる
-
-この Mac でコーディングエージェント(Claude Code、Codex など)を使っている場合は、手順を手作業で進める代わりに、次のプロンプトを貼り付けてください。エージェントは vphone スキルを読み、設定済みの部分を確認して Launchpad と `VPhone.bundle` をインストールします。管理者パスワードや macOS 復旧モードでの変更など、あなたの操作が必要な手順では止まって確認します。
-
-```text
-この Mac に vphone をセットアップしてください。まず次のスキルを読んでください:
-https://raw.githubusercontent.com/Lakr233/vphone-cli/main/Skills/vphone-guest-control/SKILL.md
-および同じフォルダの references/ 以下にリンクされたファイルを読み、その手順に従います:
-公証済みの最新の vphone-launchpad をインストールし(すべてのリリースに
--notarized zip があるわけではありません)、vphone-launchpad-cli を PATH に通し、
-Launchpad と同じシリーズの VPhone.bundle をインストールして、
-`vphone-launchpad-cli status` で確認してください。SIP、boot-args などホストの
-セキュリティ設定は変更せず、ファームウェアと空きディスク容量を私が確認するまで
-マシンは作成しないでください。私の操作が必要な手順では、何をすればよいかを
-正確に伝えて待ってください。
-```
-
-## パッケージ環境のインストール
-
-仮想マシンには標準でパッケージマネージャが入っていません。インストール手順は次のとおりです。
-
-1. メニューバーで **Apps > Install Bootstrap…** を選び、レイアウトとして **roothide** を選択します(**rootless** は非推奨です)。仮想マシンに Irisin がインストールされます。
-2. Irisin で **OwnGoal Packages** リポジトリを開き、**OwnGoal Bootstrap for vphone**(`owngoal-bootstrap-vphone`)を **Bootstrap Install** でインストールします。
-
- このパッケージ 1 つで、仮想マシンに必要なものが一度にそろいます:`apt` と `dpkg`、`bash`、`zsh` と `dash`、`sudo`、基本的なコマンドラインツール、`openssh-server`、`curl`、`wget`、`vim`、`git`、`uikittools`、`launchctl`、そして OwnGoal のアプリです。これらを一つずつインストールしないでください。一部のパッケージは相互に依存しており、`openssh-server` には循環した依存の記述があるため、個別にインストールすると途中で失敗することがあります。
-3. 初回のインストール後は、ほかのパッケージを通常どおりインストールできます。
-
-初回のインストールに失敗した場合や、環境が不整合な状態になった場合は、その場で修復しようとせず、**Apps > Uninstall Bootstrap…** で環境を削除し、手順 1 からインストールし直してください。
-
-環境を削除するには **Apps > Uninstall Bootstrap…** を選びます。削除後、仮想マシンは再起動します。
-
-Option キーを押しながら **Apps** メニューを開くと、さらに 2 つの項目があります。
-
-- **Install Bootstrap from File…**:ローカルの Irisin `.deb` を使ってインストールします。
-- **Uninstall Bootstrap Without Restarting…**:仮想マシンを再起動せずに環境を削除します。
-
-## コマンドライン
-
-Launchpad は `VPhone.bundle` 内の `vphone-cli` を使って仮想マシンを管理しています。ターミナルから直接使うこともできます。
-
-| 操作 | コマンド |
-| --- | --- |
-| 仮想マシンの一覧表示 | `vphone-cli vm list` |
-| 仮想マシンの情報表示 | `vphone-cli vm info myphone` |
-| 仮想マシンの起動 | `vphone-cli vm launch myphone` |
-| 仮想マシンの停止 | `vphone-cli vm stop myphone` |
-| 仮想マシンの複製 | `vphone-cli vm clone myphone copy` |
-| 仮想マシンの書き出し | `vphone-cli vm export myphone --out myphone.tzst` |
-| 仮想マシンの読み込み | `vphone-cli vm import myphone.tzst --name restored` |
-
-仮想マシンは標準で `~/.vphone/` に保存されます。すべてのコマンドは `vphone-cli <group> --help` で確認できます。Launchpad を使わずに仮想マシンを作成する方法は[作成と実行](Guides/create-and-run.md)をご覧ください。
-
-### 自動化 API
-
-起動時に `--api-listen` を指定すると有効になります。
-
-```sh
-vphone-cli vm launch myphone --api-listen 127.0.0.1:8765
-# 出力に [api] token: … と表示されます
-curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8765/v1/health
-```
-
-token は起動のたびに新しく生成されます。token を固定するには、環境変数 `VPHONE_API_TOKEN` を設定してください。token のないリクエストと Web ページからのリクエストは、どちらも拒否されます。インターフェースの説明は [API ドキュメント](../Research/vphoned_http_api.md)をご覧ください。
-
-## ブート ROM
-
-新しく作成した仮想マシンは、Virtualization.framework に含まれるクローズドな ROM ではなく、2 つのオープンソース ROM から起動します。
-
-- [OpenAVB](https://github.com/owngoal-dev/OpenAVB) はブート ROM の AVPBooter の代わりです。パッチが不要なので、`fw patch` は変更しません。
-- [OpenSEP](https://github.com/owngoal-dev/OpenSEP) は SEP ブート ROM の AVPSEPBooter の代わりです。
-
-両方を使うと、iBoot と SEPOS より前に実行されるコードに Apple が書いたものはなくなります。どちらもビルド済みの状態で `VPhone.bundle` に含まれており、固定した上流のコミットからビルドされています。それぞれの説明([OpenAVB](../VPhoneExecutable/VPhoneVirtualization/Resources/OpenAVB/README.md)、[OpenSEP](../VPhoneExecutable/VPhoneVirtualization/Resources/OpenSEP/README.md))に、ソースからビルドし直してバイト単位で照合する方法があります。
-
-以前のバージョンで作成した仮想マシンは Apple の ROM のままです。どちらの ROM にも、システムを復元し直さずに切り替えられます。次回の起動から反映されます。
-
-```sh
-vphone-cli vm config myphone --rom openavb --seprom opensep # オープンソース ROM
-vphone-cli vm config myphone --rom apple --seprom apple # Apple の ROM
-```
-
-`vphone-cli vm info myphone` で仮想マシンが使っている ROM を確認できます。OpenAVB で起動する仮想マシンを復元するには、`VPhone.bundle` 2.10.1 以降が必要です。詳しくは研究記録の [OpenAVB](../Research/Firmware/openavb_boot_rom.md) と [OpenSEP](../Research/Firmware/opensep_sep_rom.md) をご覧ください。
-
-## 問題が起きたら
-
-まず[トラブルシューティング](Guides/troubleshooting.md)をご覧ください。仮想マシン用プログラムがシステムに拒否される、復元に失敗する、「Press home to continue」で止まる、といった状況を扱っています。それでも解決しない場合は、[issue を送信](https://github.com/Lakr233/vphone-cli/issues)してください。
-
-## ドキュメント
-
-| ドキュメント | 内容 |
-| --- | --- |
-| [ダウンロードガイド](Downloads/README.md) | 公証済みの Launchpad バージョンと対応する `VPhone.bundle` バージョン |
-| [ホストの設定](Guides/host-setup.md) | SIP と AMFI の設定、ソースからのビルド、環境の確認 |
-| [作成と実行](Guides/create-and-run.md) | 作成の流れ、仮想マシンの起動と停止 |
-| [テンプレート](Guides/templates.md) | 1 回の復元から複数の仮想マシンを作成し、ゲストを軽量化する |
-| [ライブラリとバックアップ](Guides/library-and-backups.md) | 仮想マシンの保存場所、複製と書き出し |
-| [互換性ガイド](Guides/compatibility.md) | 検証済みのファームウェアの組み合わせ |
-| [スナップショット](Guides/snapshots.md) | 停止中の仮想マシンのディスク状態を保存し、その状態に戻す |
-| [iPadOS ゲスト](Guides/ipados.md) | iOS の代わりに iPadOS を実行する |
-| [その他の iPhone モデル](Guides/iphone-models.md) | 別の iPhone モデルの IPSW で iOS を実行する |
-| [パッケージ環境](Guides/package-environment.md) | 仮想マシンのパッケージマネージャのインストールと削除 |
-| [トラブルシューティング](Guides/troubleshooting.md) | よくあるエラーと対処方法 |
-| [ネットワーク](Guides/networking.md) | ネットワークモード、アドレス、ポート転送と、Mac が VPN やプロキシを使うときの `tunnel` |
-| [Launchpad コマンドライン](Guides/launchpad-cli.md) | `vphone-launchpad-cli` でローカルビルドをインストールしてテストする |
-| [すべてのガイド](README.md) | 主題別にまとめたすべてのガイド |
-| [研究記録](../Research/README.md) | パッチと実装の詳細 |
-
-## プロジェクト構成
-
-- `vphone-launchpad`:Mac App です。`VPhone.bundle` のダウンロードとインストール、ホストの設定を行います。別途配布されます。
-- `vphone-cli`:ファームウェアの準備、パッチの適用、システムの復元、仮想マシンの管理を行います。
-- `vphone-vm`:仮想マシンを実行し、仮想マシンのウィンドウを表示します。
-- `vphoned`:仮想マシン内の制御サービスです。ウィンドウの機能と API は、すべてこれを通じて実現されています。
-
-| パス | 内容 |
-| --- | --- |
-| [`VPhoneExecutable/`](../VPhoneExecutable/) | `vphone-cli`、`vphone-vm`、ファームウェアパッチと復元 |
-| [`VPhoneKit/`](../VPhoneKit/) | ホスト側の共有ライブラリと API クライアント |
-| [`VPhoneDaemon/`](../VPhoneDaemon/) | `vphoned` |
-| [`VPhoneGuestComponents/`](../VPhoneGuestComponents/) | 仮想マシン内のフックと補助プログラム |
-| [`VPhoneLaunchpad/`](../VPhoneLaunchpad/) | Launchpad App とそのヘルパー |
-
-ソースからのビルド:`xcodebuild -workspace VPhone.xcworkspace -scheme VPhone build`。成果物は `VPhone.bundle` です。
-
-## 謝辞
-
-- [wh1te4ever/super-tart-vphone-writeup](https://github.com/wh1te4ever/super-tart-vphone-writeup)
-- [owngoal-dev/OpenAVB](https://github.com/owngoal-dev/OpenAVB) と [owngoal-dev/OpenSEP](https://github.com/owngoal-dev/OpenSEP):新しい仮想マシンが起動に使うブート ROM
diff --git a/Documents/README_ko.md b/Documents/README_ko.md
deleted file mode 100644
index 688cacba..00000000
--- a/Documents/README_ko.md
+++ /dev/null
@@ -1,170 +0,0 @@
-<div align="right"><a href="../README.md">English</a> · <a href="README_zh.md">中文</a> · <a href="README_ja.md">日本語</a> · <strong>한국어</strong></div>
-
-# vphone-cli
-
-Apple Silicon Mac에서 가상 iPhone을 실행합니다.
-
-> [!WARNING]
-> 본 프로젝트는 암호화폐나 토큰을 발행하거나 그 발행을 승인한 적이 없으며, 암호화폐 결제나 기부도 받지 않습니다. 본 프로젝트의 이름을 내세워 발행·홍보하거나 본 프로젝트와의 관련성을 주장하는 암호화폐와 토큰은 모두 사기입니다.
-
-![macOS에서 실행 중인 가상 iPhone](demo.jpeg)
-
-vphone-cli는 Apple의 Virtualization.framework와 PCC 연구용 가상 머신으로 iOS를 실행하며, 보안 연구, 리버스 엔지니어링, 디버깅에 적합합니다.
-
-- **그래픽 창**: Mac에서 가상 iPhone의 화면을 조작하고, 앱과 파일을 탐색하며, 스크린샷을 찍고 화면을 녹화합니다.
-- **커스텀 펌웨어(Custom Firmware)**: 시스템에 패치가 미리 적용되어 있어 패키지 환경을 설치할 수 있습니다.
-- **백업과 복제**: 가상 머신을 내보내고, 가져오고, 복제할 수 있습니다.
-- **자동화 API**: 선택적으로 사용할 수 있는 로컬 HTTP 및 WebSocket 인터페이스입니다.
-- **추가 의존성 없음**: 실행에 Xcode, Python, Homebrew가 필요하지 않습니다.
-
-## 준비 사항
-
-- macOS 15 이상을 실행하는 물리 Apple Silicon Mac. macOS 가상 머신에서는 사용할 수 없습니다.
-- 충분한 디스크 공간. 가상 머신마다 기본적으로 64 GB 가상 디스크를 사용하며, 펌웨어와 임시 파일이 별도로 공간을 차지합니다.
-- 네트워크 연결. 시스템을 복원할 때 서명 티켓을 온라인으로 받아야 합니다.
-- 보안 설정 변경. macOS 복구 모드로 진입하여 터미널에서 다음 명령을 실행한 뒤 재시동합니다.
-
- ```sh
- csrutil enable --without debug
- csrutil allow-research-guests enable
- ```
-
- SIP는 켜진 상태로 유지되며 디버깅 제한만 완화됩니다. 이유와 다른 설정 방법은 [호스트 설정](Guides/host-setup.md)을 참고하세요.
-
-## 빠른 시작
-
-1. [최신 릴리스](https://github.com/Lakr233/vphone-cli/releases/latest)에서 `vphone-launchpad-<버전>-notarized.zip`을 내려받아 압축을 풀고 엽니다. 모든 릴리스가 공증된 것은 아닙니다. 최신 릴리스에 `-notarized` 파일이 없으면 [다운로드 안내](Downloads/README.md)에서 공증된 버전을 선택하세요.
-2. **Host Setup**에서 개발자 도구 권한을 부여하고 도우미 프로그램을 설치합니다.
-3. **Core Bundle**에서 **Download and Install**을 클릭합니다. Launchpad가 `VPhone.bundle`을 내려받아 검증한 뒤, 그 안의 가상 머신 프로그램이 이 Mac에서 실행되도록 허용합니다.
-4. **Machines**에서 **New Machine**을 클릭하고 펌웨어 조합을 선택한 뒤 **Create**를 클릭합니다.
-
-Launchpad가 펌웨어를 내려받고, 패치를 적용하고, 시스템을 복원한 뒤 첫 부팅을 진행합니다. 완료되면 가상 머신은 계속 실행됩니다.
-
-직접 준비한 iPhone 및 cloudOS IPSW를 사용할 수도 있습니다. 검증된 조합은 [호환성 안내](Guides/compatibility.md)를 참고하세요.
-
-### 에이전트에게 맡기기
-
-이 Mac에서 코딩 에이전트(Claude Code, Codex 등)를 사용한다면 직접 단계를 따라 하는 대신 아래 프롬프트를 붙여 넣으세요. 에이전트는 vphone 스킬을 읽고, 이미 준비된 부분을 확인한 뒤 Launchpad와 `VPhone.bundle`을 설치합니다. 관리자 암호나 macOS 복구 모드에서의 변경처럼 사용자가 해야 하는 단계에서는 멈추고 물어봅니다.
-
-```text
-이 Mac에 vphone을 설정해 주세요. 먼저 다음 스킬을 읽으세요:
-https://raw.githubusercontent.com/Lakr233/vphone-cli/main/Skills/vphone-guest-control/SKILL.md
-그리고 같은 폴더의 references/ 아래에 링크된 파일을 읽고 그대로 따라 하세요:
-공증된 최신 vphone-launchpad를 설치하고(모든 릴리스에 -notarized zip이 있는 것은
-아닙니다), vphone-launchpad-cli를 PATH에 추가하고, Launchpad와 같은 시리즈의
-VPhone.bundle을 설치한 뒤 `vphone-launchpad-cli status`로 확인하세요. SIP,
-boot-args 등 호스트 보안 설정은 변경하지 말고, 펌웨어와 여유 디스크 공간을
-제가 확인하기 전에는 머신을 만들지 마세요. 제가 해야 하는 단계에서는 무엇을
-해야 하는지 정확히 알려 주고 기다리세요.
-```
-
-## 패키지 환경 설치
-
-가상 머신에는 기본적으로 패키지 관리자가 없습니다. 설치 방법은 다음과 같습니다.
-
-1. 메뉴 막대에서 **Apps > Install Bootstrap…**을 선택하고 레이아웃으로 **roothide**를 선택합니다(**rootless**는 더 이상 권장되지 않습니다). 가상 머신에 Irisin이 설치됩니다.
-2. Irisin에서 **OwnGoal Packages** 저장소를 열고 **OwnGoal Bootstrap for vphone**(`owngoal-bootstrap-vphone`)을 **Bootstrap Install**로 설치합니다.
-
- 이 패키지 하나로 가상 머신에 필요한 것이 한 번에 설치됩니다: `apt`와 `dpkg`, `bash`, `zsh`와 `dash`, `sudo`, 기본 명령줄 도구, `openssh-server`, `curl`, `wget`, `vim`, `git`, `uikittools`, `launchctl`, 그리고 OwnGoal 앱. 이 패키지들을 하나씩 설치하지 마십시오. 일부 패키지는 서로 의존하며, `openssh-server`는 순환하는 의존성 선언을 포함하고 있어 따로 설치하면 도중에 실패할 수 있습니다.
-3. 처음 설치를 마친 뒤에는 다른 패키지를 일반 설치로 설치하면 됩니다.
-
-처음 설치에 실패했거나 설치 후 환경이 비정상적인 상태가 되었다면 그 자리에서 복구하려 하지 말고, **Apps > Uninstall Bootstrap…**으로 환경을 삭제한 뒤 1단계부터 다시 설치하십시오.
-
-환경을 삭제하려면 **Apps > Uninstall Bootstrap…**을 선택합니다. 삭제 후 가상 머신이 재시동됩니다.
-
-Option 키를 누른 채 **Apps** 메뉴를 열면 두 가지 항목이 더 있습니다.
-
-- **Install Bootstrap from File…**: 로컬 Irisin `.deb`로 설치합니다.
-- **Uninstall Bootstrap Without Restarting…**: 가상 머신을 재시동하지 않고 환경을 삭제합니다.
-
-## 명령줄
-
-Launchpad는 `VPhone.bundle` 안의 `vphone-cli`로 가상 머신을 관리하며, 터미널에서 직접 사용할 수도 있습니다.
-
-| 작업 | 명령 |
-| --- | --- |
-| 가상 머신 목록 보기 | `vphone-cli vm list` |
-| 가상 머신 정보 보기 | `vphone-cli vm info myphone` |
-| 가상 머신 시작 | `vphone-cli vm launch myphone` |
-| 가상 머신 중지 | `vphone-cli vm stop myphone` |
-| 가상 머신 복제 | `vphone-cli vm clone myphone copy` |
-| 가상 머신 내보내기 | `vphone-cli vm export myphone --out myphone.tzst` |
-| 가상 머신 가져오기 | `vphone-cli vm import myphone.tzst --name restored` |
-
-가상 머신은 기본적으로 `~/.vphone/`에 저장됩니다. 전체 명령은 `vphone-cli <group> --help`로 확인하세요. Launchpad 없이 가상 머신을 만드는 방법은 [생성 및 실행](Guides/create-and-run.md)을 참고하세요.
-
-### 자동화 API
-
-시작할 때 `--api-listen`을 추가하면 활성화됩니다.
-
-```sh
-vphone-cli vm launch myphone --api-listen 127.0.0.1:8765
-# 출력에 [api] token: …이 표시됩니다
-curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8765/v1/health
-```
-
-시작할 때마다 새 token이 생성됩니다. 고정된 token을 사용하려면 환경 변수 `VPHONE_API_TOKEN`을 설정하세요. token이 없는 요청과 웹 페이지에서 온 요청은 모두 거부됩니다. 인터페이스 설명은 [API 문서](../Research/vphoned_http_api.md)를 참고하세요.
-
-## 부트 ROM
-
-새로 만든 가상 머신은 Virtualization.framework에 포함된 비공개 ROM 대신 두 가지 오픈 소스 ROM으로 부팅합니다.
-
-- [OpenAVB](https://github.com/owngoal-dev/OpenAVB)는 부트 ROM인 AVPBooter를 대신합니다. 패치가 필요 없으므로 `fw patch`가 건드리지 않습니다.
-- [OpenSEP](https://github.com/owngoal-dev/OpenSEP)는 SEP 부트 ROM인 AVPSEPBooter를 대신합니다.
-
-둘을 함께 쓰면 iBoot와 SEPOS 이전에 실행되는 코드 중 Apple이 작성한 것은 없습니다. 두 ROM 모두 미리 빌드된 상태로 `VPhone.bundle`에 포함되며, 고정된 업스트림 커밋에서 빌드됩니다. 각각의 설명([OpenAVB](../VPhoneExecutable/VPhoneVirtualization/Resources/OpenAVB/README.md), [OpenSEP](../VPhoneExecutable/VPhoneVirtualization/Resources/OpenSEP/README.md))에 소스에서 다시 빌드하고 바이트 단위로 대조하는 방법이 있습니다.
-
-이전 버전에서 만든 가상 머신은 Apple의 ROM을 그대로 사용합니다. 시스템을 다시 복원하지 않고 어느 쪽으로든 전환할 수 있으며, 다음 시작부터 적용됩니다.
-
-```sh
-vphone-cli vm config myphone --rom openavb --seprom opensep # 오픈 소스 ROM
-vphone-cli vm config myphone --rom apple --seprom apple # Apple의 ROM
-```
-
-`vphone-cli vm info myphone`으로 가상 머신이 사용하는 ROM을 확인할 수 있습니다. OpenAVB로 부팅하는 가상 머신을 복원하려면 `VPhone.bundle` 2.10.1 이상이 필요합니다. 자세한 내용은 연구 기록의 [OpenAVB](../Research/Firmware/openavb_boot_rom.md)와 [OpenSEP](../Research/Firmware/opensep_sep_rom.md)를 참고하세요.
-
-## 문제가 생기면
-
-먼저 [문제 해결](Guides/troubleshooting.md)을 확인하세요. 시스템이 가상 머신 프로그램을 거부하는 경우, 복원 실패, “Press home to continue”에서 멈추는 경우 등을 다룹니다. 그래도 해결되지 않으면 [이슈를 등록](https://github.com/Lakr233/vphone-cli/issues)해 주세요.
-
-## 문서
-
-| 문서 | 내용 |
-| --- | --- |
-| [다운로드 안내](Downloads/README.md) | 공증된 Launchpad 버전과 맞는 `VPhone.bundle` 버전 |
-| [호스트 설정](Guides/host-setup.md) | SIP 및 AMFI 설정, 소스 빌드, 환경 점검 |
-| [생성 및 실행](Guides/create-and-run.md) | 생성 절차, 가상 머신 시작과 중지 |
-| [템플릿](Guides/templates.md) | 한 번의 복원으로 여러 가상 머신 만들기, 게스트 경량화 |
-| [보관함과 백업](Guides/library-and-backups.md) | 가상 머신 저장 위치, 복제와 내보내기 |
-| [호환성 안내](Guides/compatibility.md) | 검증된 펌웨어 조합 |
-| [스냅샷](Guides/snapshots.md) | 중지된 가상 머신의 디스크 상태를 저장하고 되돌리기 |
-| [iPadOS 게스트](Guides/ipados.md) | iOS 대신 iPadOS 실행 |
-| [다른 iPhone 모델](Guides/iphone-models.md) | 다른 iPhone 모델의 IPSW로 iOS 실행 |
-| [패키지 환경](Guides/package-environment.md) | 가상 머신의 패키지 관리자 설치 및 제거 |
-| [문제 해결](Guides/troubleshooting.md) | 자주 발생하는 오류와 해결 방법 |
-| [네트워크](Guides/networking.md) | 네트워크 모드, 주소, 포트 포워딩, 그리고 Mac이 VPN이나 프록시를 쓸 때의 `tunnel` |
-| [Launchpad 명령줄](Guides/launchpad-cli.md) | `vphone-launchpad-cli`로 로컬 빌드 설치 및 테스트 |
-| [전체 가이드](README.md) | 주제별로 정리한 전체 가이드 |
-| [연구 기록](../Research/README.md) | 패치와 구현 세부 사항 |
-
-## 프로젝트 구조
-
-- `vphone-launchpad`: `VPhone.bundle`을 내려받아 설치하고 호스트를 설정하는 Mac 앱입니다. 별도로 배포됩니다.
-- `vphone-cli`: 펌웨어 준비, 패치 적용, 시스템 복원, 가상 머신 관리를 담당합니다.
-- `vphone-vm`: 가상 머신을 실행하고 가상 머신 창을 표시합니다.
-- `vphoned`: 가상 머신 안의 제어 서비스로, 창의 기능과 API는 모두 이를 통해 동작합니다.
-
-| 경로 | 내용 |
-| --- | --- |
-| [`VPhoneExecutable/`](../VPhoneExecutable/) | `vphone-cli`, `vphone-vm`, 펌웨어 패치와 복원 |
-| [`VPhoneKit/`](../VPhoneKit/) | 호스트 공용 라이브러리와 API 클라이언트 |
-| [`VPhoneDaemon/`](../VPhoneDaemon/) | `vphoned` |
-| [`VPhoneGuestComponents/`](../VPhoneGuestComponents/) | 가상 머신 안의 hook과 도우미 프로그램 |
-| [`VPhoneLaunchpad/`](../VPhoneLaunchpad/) | Launchpad 앱과 도우미 프로그램 |
-
-소스에서 빌드하려면 `xcodebuild -workspace VPhone.xcworkspace -scheme VPhone build`를 실행합니다. 결과물은 `VPhone.bundle`입니다.
-
-## 감사의 말
-
-- [wh1te4ever/super-tart-vphone-writeup](https://github.com/wh1te4ever/super-tart-vphone-writeup)
-- [owngoal-dev/OpenAVB](https://github.com/owngoal-dev/OpenAVB)와 [owngoal-dev/OpenSEP](https://github.com/owngoal-dev/OpenSEP): 새 가상 머신이 부팅에 쓰는 부트 ROM
diff --git a/Documents/README_zh.md b/Documents/README_zh.md
deleted file mode 100644
index 4e415bce..00000000
--- a/Documents/README_zh.md
+++ /dev/null
@@ -1,169 +0,0 @@
-<div align="right"><a href="../README.md">English</a> · <strong>中文</strong> · <a href="README_ja.md">日本語</a> · <a href="README_ko.md">한국어</a></div>
-
-# vphone-cli
-
-在 Apple Silicon Mac 上运行虚拟 iPhone。
-
-> [!WARNING]
-> 本项目从未发行或授权发行任何虚拟货币或代币,也不接受任何虚拟货币付款或捐赠。任何以本项目名义发行、推广或声称与本项目有关的虚拟货币或代币,均属诈骗。
-
-![在 macOS 上运行的虚拟 iPhone](demo.jpeg)
-
-vphone-cli 使用 Apple 的 Virtualization.framework 和 PCC 研究虚拟机运行 iOS,适合安全研究、逆向工程和调试。
-
-- **图形窗口**:在 Mac 上操作虚拟 iPhone 的屏幕,浏览 App 和文件,截屏和录屏。
-- **自定义固件(Custom Firmware)**:系统已预先打好补丁,可以安装软件包环境。
-- **备份与克隆**:虚拟机可以导出、导入和克隆。
-- **自动化 API**:可选的本机 HTTP 和 WebSocket 接口。
-- **无需额外依赖**:运行时不需要 Xcode、Python 或 Homebrew。
-
-## 准备工作
-
-- 一台实体 Apple Silicon Mac,运行 macOS 15 或更新版本。macOS 虚拟机中无法使用。
-- 足够的磁盘空间。每台虚拟机默认使用 64 GB 虚拟磁盘,固件和临时文件另外占用空间。
-- 网络连接。恢复系统时需要在线获取签名票据。
-- 修改安全设置。启动进入 macOS 恢复,在终端中执行以下命令,然后重新启动:
-
- ```sh
- csrutil enable --without debug
- csrutil allow-research-guests enable
- ```
-
- SIP 仍保持启用,只放宽调试限制。原因和其他设置方式见[宿主机设置](Guides/host-setup.md)。
-
-## 快速开始
-
-1. 从[最新版本](https://github.com/Lakr233/vphone-cli/releases/latest)下载 `vphone-launchpad-<版本>-notarized.zip`,解压并打开。并非每个版本都经过公证。如果最新版本没有 `-notarized` 文件,请在[下载说明](Downloads/README.md)中选择一个已公证的版本。
-2. 在 **Host Setup** 中授予开发者工具权限,并安装辅助程序。
-3. 在 **Core Bundle** 中点击 **Download and Install**。Launchpad 会下载并校验 `VPhone.bundle`,然后允许其中的虚拟机程序在本机运行。
-4. 在 **Machines** 中点击 **New Machine**,选择固件组合,点击 **Create**。
-
-Launchpad 会下载固件、打补丁、恢复系统并首次启动。完成后虚拟机会继续运行。
-
-也可以使用自己的 iPhone 和 cloudOS IPSW,已验证的组合见[兼容性说明](Guides/compatibility.md)。
-
-### 让 Agent 代劳
-
-如果这台 Mac 上有编程 Agent(Claude Code、Codex 等),可以直接粘贴下面的提示词,不必手动操作。Agent 会读取 vphone skill,检查已完成的部分,安装 Launchpad 和 `VPhone.bundle`;遇到需要你处理的步骤(例如管理员密码,或在 macOS 恢复中进行的更改)时会停下来询问。
-
-```text
-在这台 Mac 上安装 vphone。先阅读这个 skill:
-https://raw.githubusercontent.com/Lakr233/vphone-cli/main/Skills/vphone-guest-control/SKILL.md
-以及它在 references/(同一目录)下链接的文件,然后照着做:
-安装最新的已公证 vphone-launchpad(并非每个 release 都有 -notarized 压缩包),
-把 vphone-launchpad-cli 加到 PATH,安装与 Launchpad 系列一致的 VPhone.bundle,
-并运行 `vphone-launchpad-cli status` 检查。不要修改 SIP、boot-args 或任何其他
-主机安全设置;在我确认固件和可用磁盘空间之前,不要创建虚拟机。遇到需要我
-操作的步骤,请准确告诉我该做什么,然后等待。
-```
-
-## 安装软件包环境
-
-虚拟机默认不带软件包管理器。安装步骤:
-
-1. 在菜单栏选择 **Apps > Install Bootstrap…**,布局选择 **roothide**(**rootless** 已弃用)。虚拟机中会安装 Irisin。
-2. 在 Irisin 中打开 **OwnGoal Packages** 软件源,找到 **OwnGoal Bootstrap for vphone**(`owngoal-bootstrap-vphone`),选择 **Bootstrap Install** 安装。
-
- 这一个软件包会一次装好虚拟机需要的全部内容:`apt` 和 `dpkg`、`bash`、`zsh` 和 `dash`、`sudo`、常用命令行工具、`openssh-server`、`curl`、`wget`、`vim`、`git`、`uikittools`、`launchctl`,以及 OwnGoal 的几个应用。不要逐个安装这些软件包:其中部分软件包相互依赖,`openssh-server` 的依赖声明也存在循环,逐个安装可能在中途失败。
-3. 首次安装完成后,其余软件包使用普通安装即可。
-
-如果首次安装失败,或安装后环境状态异常,不要在原环境上修复。请通过 **Apps > Uninstall Bootstrap…** 删除环境,再从第 1 步重新安装。
-
-要删除环境,选择 **Apps > Uninstall Bootstrap…**,删除后虚拟机会重启。
-
-按住 Option 打开 **Apps** 菜单,还有两个选项:
-
-- **Install Bootstrap from File…**:使用本地的 Irisin `.deb` 安装。
-- **Uninstall Bootstrap Without Restarting…**:删除环境,不重启虚拟机。
-
-## 命令行
-
-Launchpad 通过 `VPhone.bundle` 中的 `vphone-cli` 管理虚拟机,你也可以在终端中直接使用:
-
-| 操作 | 命令 |
-| --- | --- |
-| 列出虚拟机 | `vphone-cli vm list` |
-| 查看虚拟机信息 | `vphone-cli vm info myphone` |
-| 启动虚拟机 | `vphone-cli vm launch myphone` |
-| 停止虚拟机 | `vphone-cli vm stop myphone` |
-| 克隆虚拟机 | `vphone-cli vm clone myphone copy` |
-| 导出虚拟机 | `vphone-cli vm export myphone --out myphone.tzst` |
-| 导入虚拟机 | `vphone-cli vm import myphone.tzst --name restored` |
-
-虚拟机默认保存在 `~/.vphone/`。运行 `vphone-cli <group> --help` 查看全部命令。不使用 Launchpad 创建虚拟机的方法见[创建与运行](Guides/create-and-run.md)。
-
-### 自动化 API
-
-启动时加上 `--api-listen` 即可开启:
-
-```sh
-vphone-cli vm launch myphone --api-listen 127.0.0.1:8765
-# 输出中会显示 [api] token: …
-curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8765/v1/health
-```
-
-每次启动都会生成新的 token。要使用固定的 token,请设置环境变量 `VPHONE_API_TOKEN`。不带 token 的请求和来自网页的请求都会被拒绝。接口说明见 [API 文档](../Research/vphoned_http_api.md)。
-
-## 启动 ROM
-
-新建的虚拟机不再使用 Virtualization.framework 自带的闭源 ROM,而是从两个开源 ROM 启动:
-
-- [OpenAVB](https://github.com/owngoal-dev/OpenAVB) 替代启动 ROM AVPBooter。它不需要打补丁,`fw patch` 不会改动它。
-- [OpenSEP](https://github.com/owngoal-dev/OpenSEP) 替代 SEP 启动 ROM AVPSEPBooter。
-
-两者同时使用时,iBoot 和 SEPOS 之前不会运行任何由 Apple 编写的代码。两个 ROM 都以预编译形式随 `VPhone.bundle` 发布,由固定的上游提交构建。各自的说明([OpenAVB](../VPhoneExecutable/VPhoneVirtualization/Resources/OpenAVB/README.md)、[OpenSEP](../VPhoneExecutable/VPhoneVirtualization/Resources/OpenSEP/README.md))写了如何从源码重新构建并逐字节核对。
-
-旧版本创建的虚拟机仍使用 Apple 的 ROM。两种 ROM 可以随时切换,不需要重新恢复系统,下次启动时生效:
-
-```sh
-vphone-cli vm config myphone --rom openavb --seprom opensep # 开源 ROM
-vphone-cli vm config myphone --rom apple --seprom apple # Apple 的 ROM
-```
-
-`vphone-cli vm info myphone` 会显示虚拟机使用的 ROM。恢复使用 OpenAVB 启动的虚拟机,需要 `VPhone.bundle` 2.10.1 或更新版本。详细内容见研究记录中的 [OpenAVB](../Research/Firmware/openavb_boot_rom.md) 和 [OpenSEP](../Research/Firmware/opensep_sep_rom.md)。
-
-## 遇到问题
-
-请先查看[故障排查](Guides/troubleshooting.md),其中包括虚拟机程序被系统拒绝、恢复失败、停在 “Press home to continue” 等情况。如果仍未解决,请[提交 issue](https://github.com/Lakr233/vphone-cli/issues)。
-
-## 文档
-
-| 文档 | 内容 |
-| --- | --- |
-| [下载说明](Downloads/README.md) | 已公证的 Launchpad 版本及匹配的 `VPhone.bundle` 版本 |
-| [宿主机设置](Guides/host-setup.md) | SIP 与 AMFI 设置、源码构建、环境检查 |
-| [创建与运行](Guides/create-and-run.md) | 创建流程、启动与停止虚拟机 |
-| [模板](Guides/templates.md) | 用一次恢复创建多台虚拟机,精简客户机系统 |
-| [资料库与备份](Guides/library-and-backups.md) | 虚拟机的存放位置、克隆与导出 |
-| [兼容性说明](Guides/compatibility.md) | 已验证的固件组合 |
-| [快照](Guides/snapshots.md) | 保存已停止虚拟机的磁盘状态,并可恢复到该状态 |
-| [iPadOS 客户机](Guides/ipados.md) | 运行 iPadOS 而非 iOS |
-| [其他 iPhone 机型](Guides/iphone-models.md) | 使用其他 iPhone 机型的 IPSW 运行 iOS |
-| [软件包环境](Guides/package-environment.md) | 安装和删除虚拟机中的软件包管理器 |
-| [故障排查](Guides/troubleshooting.md) | 常见错误及解决方法 |
-| [网络](Guides/networking.md) | 网络模式、地址、端口转发,以及在 Mac 使用 VPN 或代理时用的 `tunnel` |
-| [Launchpad 命令行](Guides/launchpad-cli.md) | 用 `vphone-launchpad-cli` 安装和测试本地构建 |
-| [全部指南](README.md) | 按主题分组的全部指南 |
-| [研究记录](../Research/README.md) | 补丁与实现细节 |
-
-## 项目结构
-
-- `vphone-launchpad`:Mac App,负责下载和安装 `VPhone.bundle`、配置宿主机。单独发布。
-- `vphone-cli`:准备固件、打补丁、恢复系统、管理虚拟机。
-- `vphone-vm`:运行虚拟机并显示虚拟机窗口。
-- `vphoned`:虚拟机中的控制服务,窗口中的功能和 API 都通过它实现。
-
-| 路径 | 内容 |
-| --- | --- |
-| [`VPhoneExecutable/`](../VPhoneExecutable/) | `vphone-cli`、`vphone-vm`、固件补丁与恢复 |
-| [`VPhoneKit/`](../VPhoneKit/) | 宿主机共享库与 API 客户端 |
-| [`VPhoneDaemon/`](../VPhoneDaemon/) | `vphoned` |
-| [`VPhoneGuestComponents/`](../VPhoneGuestComponents/) | 虚拟机中的 hook 与辅助程序 |
-| [`VPhoneLaunchpad/`](../VPhoneLaunchpad/) | Launchpad App 及其辅助程序 |
-
-从源码构建:`xcodebuild -workspace VPhone.xcworkspace -scheme VPhone build`,产物为 `VPhone.bundle`。
-
-## 致谢
-
-- [wh1te4ever/super-tart-vphone-writeup](https://github.com/wh1te4ever/super-tart-vphone-writeup)
-- [owngoal-dev/OpenAVB](https://github.com/owngoal-dev/OpenAVB) 和 [owngoal-dev/OpenSEP](https://github.com/owngoal-dev/OpenSEP):新虚拟机使用的启动 ROM
diff --git a/Documents/en/README.md b/Documents/en/README.md
new file mode 100644
index 00000000..d85aeaca
--- /dev/null
+++ b/Documents/en/README.md
@@ -0,0 +1,70 @@
+# vphone Manual
+
+New to vphone? Read [Overview](get-started/overview.md), then follow [Quick Start](get-started/quick-start.md).
+
+## Get Started
+
+| Page | Use it for |
+| --- | --- |
+| [Overview](get-started/overview.md) | What vphone is, what it needs, and the programs it ships |
+| [Quick Start](get-started/quick-start.md) | Your first VM with Launchpad, or with a coding agent |
+| [Host Setup](get-started/host-setup.md) | SIP, AMFI and Research Guests settings on the Mac |
+| [Downloads](get-started/downloads.md) | Notarized Launchpad versions and matching `VPhone.bundle` versions |
+
+## Machines
+
+| Page | Use it for |
+| --- | --- |
+| [Create and Run](machines/create-and-run.md) | Creating, starting and stopping a VM from Terminal |
+| [Boot ROMs](machines/boot-roms.md) | Switching between OpenAVB/OpenSEP and Apple's ROMs |
+| [Automation API](machines/automation-api.md) | The optional local HTTP and WebSocket interface |
+| [Device Name and Clock](machines/device-name-and-clock.md) | What the guest takes from the VM name and the Mac's clock |
+| [Package Environment](machines/package-environment.md) | Installing and removing a package manager in the guest |
+
+## Firmware and Devices
+
+| Page | Use it for |
+| --- | --- |
+| [Compatibility](firmware/compatibility.md) | Verified iPhone and cloudOS firmware pairs |
+| [Firmware Preparation](firmware/firmware-preparation.md) | GPU driver restore, kernelcache mixes for newer cloudOS |
+| [Other iPhone Models](firmware/iphone-models.md) | Running iOS from another iPhone model's IPSW |
+| [iPadOS Guests](firmware/ipados.md) | Running iPadOS instead of iOS |
+
+## Storage and Backups
+
+| Page | Use it for |
+| --- | --- |
+| [Library and Backups](storage/library-and-backups.md) | Where VMs and caches live, clones and exports |
+| [Snapshots](storage/snapshots.md) | Saving a stopped VM's disk and reverting to it |
+| [Templates](storage/templates.md) | Reusing one restore for many VMs |
+| [Building Templates](storage/template-building.md) | Turning a VM into a template and finding templates |
+| [Sharing Disk Space](storage/sharing-disk-space.md) | `vm rebase` for VMs restored separately |
+| [Create Many Machines](storage/many-machines.md) | `vm create-bulk` from a plist |
+| [Shader Caches](storage/shader-cache.md) | Persistent shader caches on an existing VM |
+
+## Networking
+
+| Page | Use it for |
+| --- | --- |
+| [Network Modes](networking/overview.md) | Choosing a mode, unplugging a running VM |
+| [Tunnel Mode](networking/tunnel.md) | A Mac behind a VPN or proxy app |
+| [MAC and IP Addresses](networking/addresses.md) | The saved MAC, old leases, fixed addresses |
+| [Port Forwarding](networking/port-forwarding.md) | Carrying a port on the Mac into the guest |
+| [Names on the Network](networking/names.md) | The guest's `.local` name and the Mac's name in the guest |
+| [Machines Reaching Each Other](networking/peers.md) | `nat` machines on one shared network |
+
+## Launchpad and Bundles
+
+| Page | Use it for |
+| --- | --- |
+| [Launchpad Command Line](launchpad/launchpad-cli.md) | Driving Launchpad with `vphone-launchpad-cli` |
+| [Core Bundles and Local Builds](launchpad/core-bundles.md) | Binding machines to bundles, testing local builds |
+| [Bundle Integration](launchpad/bundle-integration.md) | What `VPhone.bundle` contains and how an app uses it |
+
+## Help
+
+| Page | Use it for |
+| --- | --- |
+| [Troubleshooting](help/troubleshooting.md) | Launch refusals, restore failures, guest problems |
+
+Implementation notes, patch records and the full API reference are in the [research notes](../../Research/README.md), in English only.
diff --git a/Documents/Guides/compatibility.md b/Documents/en/firmware/compatibility.md
similarity index 52%
rename from Documents/Guides/compatibility.md
rename to Documents/en/firmware/compatibility.md
index 4d131c11..4ccdbfd9 100644
--- a/Documents/Guides/compatibility.md
+++ b/Documents/en/firmware/compatibility.md
@@ -1,15 +1,19 @@
# Firmware compatibility
-[Documentation](../README.md) · [Create a VM](create-and-run.md) · [Patch inventory](../../Research/0_binary_patch_comparison.md)
+Which guest firmware and cloudOS pairings are known to boot, on which hosts. Check it before you pick a release for a new machine, or when a creation fails and you want to know whether the pairing was ever tested.
-**v2.0.0 VM format:** This release starts only newly created VMs whose
-`config.plist` has `schemaVersion=2`. Recreate VMs made by earlier releases
-with `vm create`; there is no in-place upgrade. The firmware results below
-describe tested pairings, not compatibility with older VM bundles.
+To see what the current catalog offers on your Mac, run:
+
+```sh
+vphone-cli fw catalog
+```
+
+> [!NOTE]
+> Since v2.0.0, vphone starts only machines whose `config.plist` has `schemaVersion=2`. Recreate machines made by earlier releases with `vm create`; there is no in-place upgrade. The results below describe tested pairings, not compatibility with older machine bundles.
## Tested Environments
-These are the two iPhone17,3 combinations exercised with the native JB pipeline in [PR #486](https://github.com/Lakr233/vphone-cli/pull/486). Both reached the lock screen and answered a vphoned ping. A fresh 26.6.2 `vm create` also completed all stages and exited successfully after its first-boot ping.
+These are the iPhone17,3 combinations run end to end with the native JB pipeline. The two PR #486 rows ([PR #486](https://github.com/Lakr233/vphone-cli/pull/486)) reached the lock screen and answered a vphoned ping; a fresh 26.6.2 `vm create` also completed every stage and exited successfully after its first-boot ping.
| Validation | iPhone restore IPSW | PCC/cloudOS IPSW | Observed result |
| --- | --- | --- | --- |
@@ -24,11 +28,16 @@ These are the two iPhone17,3 combinations exercised with the native JB pipeline
| Research board | `11,6_18.5_22F76` | `18.5-22F76` | Minimal preset from the CLI (2026-10-21): GPU driver from a temporary cloudOS restore, kernelcache mix linked over ssh by the kmutil of macOS 15.6.1, restore, boot, vphoned; lock screen, unlock and home swipes checked |
| Research board | `11,6_18.6_22G86` | `18.6-22G86` | standard preset from Launchpad's CLI (2026-10-24): kernelcache mix (cached), restore, CFW, boot, vphoned, Hello screen; Frida 17.24.3 attach, spawn, Interceptor and Stalker with the two Frida patches allowed |
-The cloudOS 26.4 beta image (`26.4-23E5207q`) is the newest one that contains `vphone600ap`, the identity the guest's kernel, SEP and device tree come from, and it stays the recommended cloudOS: it needs nothing beyond vphone-cli. Every cloudOS release after it was checked on 2026-10-03 and lists only the PCC boards and `vresearch101ap`: `iPhone99,11` is gone from `SupportedProductTypes`, and there is no `kernelcache.*.vphone600`, `sep-firmware.vphone600` or `DeviceTree.vphone600ap`.
+### Which cloudOS to use
-On such a cloudOS the research board stands in (the Research Board patch set): `fw patch` turns its device tree and SEP into vphone600's and rebuilds its kernelcache with the vphone600 virtualization kexts, from a recipe for that kernelcache. KDK extraction is native; the link still needs root (`vphone-cli fw kernelcache`; see [the recipes](../../VPhoneExecutable/VPhoneVirtualization/Resources/kernelcache_recipes/README.md)). `fw prepare` refuses a cloudOS no recipe covers. `fw catalog` lists each iOS release's own cloudOS beside the recommended one, and Launchpad offers it under Firmware.
+Use the cloudOS 26.4 beta (`26.4-23E5207q`) unless you have a reason not to. It is the newest cloudOS that contains `vphone600ap`, the identity the guest's kernel, SEP and device tree come from, and it needs nothing beyond `vphone-cli`.
-iOS 18.1 to 18.7.2 run the same way on their own release's cloudOS, with the userland of the iPhone XS family's IPSWs (`vm create --device iPhone11,6`, the Minimal preset by default, `--preset standard` checked on 18.6; `fw catalog --device iPhone11,6` lists them). Their kernels are kernel-first: from macOS 26.4 on, another Mac or a macOS VM running macOS 15 or 26.0 to 26.3 links the mix over ssh (`VPHONE_KMUTIL_SSH`, see [Create and Run](create-and-run.md)); Launchpad offers them as the iPhone XS Max, with that Mac as the macOS builder. 18.1, 18.5 and 18.7.2 are checked on VMs; the other four recipes have not been booted yet.
+Every later cloudOS (checked on 2026-10-03) lists only the PCC boards and `vresearch101ap`: `iPhone99,11` is gone from `SupportedProductTypes`, and there is no `kernelcache.*.vphone600`, `sep-firmware.vphone600` or `DeviceTree.vphone600ap`. On such a cloudOS the research board stands in (the Research Board patch set):
+
+- `fw patch` turns the research board's device tree and SEP into vphone600's and rebuilds its kernelcache with the vphone600 virtualization kexts, from a recipe for that kernelcache.
+- KDK extraction is native; only the link needs root (`vphone-cli fw kernelcache`). See [the kernelcache recipes](../../../VPhoneExecutable/VPhoneVirtualization/Resources/kernelcache_recipes/README.md) and [Firmware preparation](firmware-preparation.md).
+- `fw prepare` refuses a cloudOS that no recipe covers.
+- `fw catalog` lists each iOS release's own cloudOS beside the recommended one, and Launchpad offers it under **Firmware**.
| cloudOS | `vresearch101ap` | `vphone600ap` | kernelcache recipe |
| --- | --- | --- | --- |
@@ -41,20 +50,26 @@ iOS 18.1 to 18.7.2 run the same way on their own release's cloudOS, with the use
| `26.6.1-23G82` | yes | no | no |
| `26.7-23H20` | yes | no | yes |
-Use `vphone-cli fw catalog` to inspect the current catalog. Other iPhone and iPad versions may work with `26.4-23E5207q`, but they have not passed this same end-to-end check.
+Other iPhone and iPad versions may work with `26.4-23E5207q`, but they have not passed the same end-to-end check.
+
+### iOS 18 guests
+
+iOS 18.1 to 18.7.2 run on their own release's cloudOS, with the userland of the iPhone XS family's IPSWs:
+
+- Create them with `vm create --device iPhone11,6`. The Minimal preset is the default; `--preset standard` was checked on 18.6.
+- `fw catalog --device iPhone11,6` lists the releases.
+- Their kernels are kernel-first. From macOS 26.4 on, another Mac or a macOS VM running macOS 15 or 26.0 to 26.3 links the mix over ssh (`VPHONE_KMUTIL_SSH`; see [Firmware preparation](firmware-preparation.md)).
+- Launchpad offers them as the iPhone XS Max, with that Mac as the macOS builder.
+
+18.1, 18.5 and 18.7.2 are checked on VMs; the other four recipes have not been booted yet.
+
+### iPhone17,3 on iOS 27.0.1
-**iPhone17,3 27.0.1 (24A446)** fails first boot on bundle 2.5.0 and earlier
-(reproduced 2026-10-04, including with the pristine Apple launchd): TXM's
-selector-24 pre-check rejects every binary at init and the boot panics with
-`unexpected SIGKILL of init`. The `txm-boot-precheck_admission` patch
-(`Research/Firmware/txm_selector24_cms_gate.md`) fixes it; verified the same
-day: `iPhone17,3 27.0.1 + 26.4-23E5207q` with the patch boots to the guest
-and answers a vphoned `device.info`. Bundle 2.6.0 is the first release that
-carries it.
+iOS 27.0.1 (24A446) fails first boot on bundle 2.5.0 and earlier (reproduced 2026-10-04, also with the pristine Apple launchd): TXM's selector-24 pre-check rejects every binary at init, and the boot panics with `unexpected SIGKILL of init`. The `txm-boot-precheck_admission` patch fixes it (see [the research note](../../../Research/Firmware/txm_selector24_cms_gate.md)). With the patch, iPhone17,3 27.0.1 on `26.4-23E5207q` boots to the guest and answers a vphoned `device.info` (verified the same day). Bundle 2.6.0 is the first release that carries it.
## macOS 26.6.2 hosts
-Checked on 2026-10-23 with Core Bundle 2.12.1, and again on 2026-10-24 with Core Bundle 2.12.2, on Mac mini M4 hosts (Mac16,10, 16 GB, macOS 26.6.2 25G83). Every machine was created from nothing, from the CLI: the research-board pairings stage their kernelcache mix as the user and link it with sudo, then `sudo vphone-cli vm create`. A default is the newest pairing `fw catalog` gives that device on this Mac, as Launchpad's New Machine selects. Each machine then booted twice headless: vphoned answered, `device.info` reported the release, and the guest's serial log showed no panic.
+Checked on 2026-10-23 with Core Bundle 2.12.1, and again on 2026-10-24 with Core Bundle 2.12.2, on Mac mini M4 hosts (Mac16,10, 16 GB, macOS 26.6.2 25G83). Every machine was created from nothing, from the CLI. The research-board pairings staged their kernelcache mix as the user and linked it with sudo, then ran `sudo vphone-cli vm create`. "Default" marks the newest pairing `fw catalog` gives that device on this Mac, which is what Launchpad's New Machine selects. Each machine then booted twice headless: vphoned answered, `device.info` reported the release, and the guest's serial log showed no panic.
| Guest | Firmware | cloudOS | Result |
| --- | --- | --- | --- |
@@ -76,24 +91,18 @@ Checked on 2026-10-23 with Core Bundle 2.12.1, and again on 2026-10-24 with Core
| AppleTV14,1 | tvOS 27.0 | — | refused before any download: needs macOS 27 |
| AudioAccessory5,1 | HomePod Software 27.2 | — | refused before any download: needs macOS 27 |
-The tvOS 27.0 (24J361) and HomePod Software 27.2 (24K120) OTAs compress their payload with LZRAVEN, which only macOS 27 unpacks. On an older Mac `fw catalog` leaves them out, so Launchpad's default for those devices is tvOS 26.6 and HomePod Software 27.0, and naming one is refused before anything is downloaded.
+The tvOS 27.0 (24J361) and HomePod Software 27.2 (24K120) OTAs compress their payload with LZRAVEN, which only macOS 27 unpacks. On an older Mac, `fw catalog` leaves them out, so Launchpad's default for those devices is tvOS 26.6 and HomePod Software 27.0, and naming one of them is refused before anything is downloaded.
-Apple TV 4K (4th generation), `AppleTV18,1` / `J265AP`, is available for
-bring-up with tvOS 27.2 beta (`24K120`) only, using its full OTA over the
-Apple TV HD 26.6 restore base and cloudOS 26.4 beta (`23E5207q`). It requires
-macOS 27 and the `tvos-4k` preset. On 2026-10-24 one machine was restored,
-had its custom firmware installed, and cold booted twice to vphoned and the 4K
-Language screen of the legacy TVSetup; setup itself was not completed. It is
-not included in the tested table above. See the
-[bring-up notes](../../Research/Firmware/tvos_support.md#apple-tv-4k-4th-generation).
+Apple TV 4K (4th generation), `AppleTV18,1` / `J265AP`, is available for bring-up only, with tvOS 27.2 beta (`24K120`): its full OTA over the Apple TV HD 26.6 restore base and cloudOS 26.4 beta (`23E5207q`). It requires macOS 27 and the `tvos-4k` preset. On 2026-10-24 one machine was restored, had its custom firmware installed, and cold booted twice to vphoned and the 4K Language screen of the legacy TVSetup; setup itself was not completed. It is not in the tested table above. See the [bring-up notes](../../../Research/Firmware/tvos_support.md#apple-tv-4k-4th-generation).
-cloudOS 26.7 (23H20) has no iPhone release to pair with. Staged with iOS 26.6.2's userland, its mix links and its 28 kernelcache patches apply; the CFW patch `_vm_fault_enter_prepare` finds no site in that kernel. It has not booted.
+cloudOS 26.7 (23H20) has no iPhone release to pair with. Staged with iOS 26.6.2's userland, its mix links and its 28 kernelcache patches apply, but the CFW patch `_vm_fault_enter_prepare` finds no site in that kernel. It has not booted.
-`vphone-escalator`'s allowlist is kept in amfid's memory, so it is lost when amfid restarts, as it did once on these hosts mid-run. Launchpad allows the bundle again when AMFI refuses it; from the CLI, run the `vphone-escalator allow` command `host preflight` prints again.
+> [!TIP]
+> `vphone-escalator` keeps its allowlist in amfid's memory, so the allowlist is lost when amfid restarts, as happened once on these hosts mid-run. Launchpad allows the bundle again when AMFI refuses it. From the CLI, run the `vphone-escalator allow` command that `host preflight` prints again.
## Other iPhone models
-See [Other iPhone models](iphone-models.md).
+Models other than iPhone17,3 are described in [Other iPhone models](iphone-models.md).
| Host | iPhone restore IPSW | PCC/cloudOS IPSW | Observed result |
| --- | --- | --- | --- |
@@ -101,28 +110,19 @@ See [Other iPhone models](iphone-models.md).
| Mac17,9 (M5 Pro) 27.0.1 | `18,2_27.0.1_24A446` (iPhone 17 Pro Max) | `26.4-23E5207q` | **boots** with the `kernel-boot-shared_region_size` patch (2026-10-06, bundle 2.6.0-local.0d5e6f90): `dyld cache mapped system-wide`, 0 panics, vphoned answers as 27.0.1, home screen at 440x956 pt @3x |
| Mac17,7 (M5 Max) 26.4 | `19,2_27.0.1_24A446` (iPhone 18 Pro) | `26.4-23E5207q` | **boots** with integrated ARM64E_X1 compatibility (2026-10-17): clean offline restore, validated root seal, vphoned ping, and Settings, Safari and Calculator launch |
-**iPhone18,1 and iPhone18,2 on iOS 27 need the shared-region patch**
-([issue #596](https://github.com/Lakr233/vphone-cli/issues/596), 27.0 and
-27.0.1). Their dyld shared cache records a `sharedRegionSize` of
-`0x185804000` on 27.0.1, larger than the `0x180000000` shared region of the
-cloudOS 26.4 guest kernel, so it cannot map even with `dyld-boot-maxslide`
-taking its slide away: launchd panics on first boot with `Library not loaded:
-/usr/lib/libSystem.B.dylib`. iPhone17,3's 27.0.1 cache (`0x17D508000`) still
-fits. Since this check, `cfw install` refuses such a cache with that
-explanation instead of leaving a guest that panics.
-
-`kernel-boot-shared_region_size` (on in `standard` for an iOS 27 base since
-2026-10-06) widens the arm64 region to `0x1C0000000` — the largest size that
-stays under the 26.4 kernel's own task-map ceilings — and `cfw install`
-measures the cache against that widened region when the VM's kernel carries
-the patch (its `PatchReceipt.plist` says so), so these devices now install and
-boot; validated on iPhone18,2 27.0.1 as above. Without the patch
-(an older bundle, or the patch unticked) the refusal stands: use iPhone17,3
-for iOS 27, or iOS 26 on these devices.
+### iPhone18,1 and iPhone18,2 on iOS 27
+
+These need the `kernel-boot-shared_region_size` patch ([issue #596](https://github.com/Lakr233/vphone-cli/issues/596), 27.0 and 27.0.1). It is on in the `standard` preset for an iOS 27 base since 2026-10-06.
+
+Their dyld shared cache records a `sharedRegionSize` of `0x185804000` on 27.0.1, larger than the `0x180000000` shared region of the cloudOS 26.4 guest kernel, so the cache cannot map even with `dyld-boot-maxslide` taking its slide away. Without the patch, launchd panics on first boot with `Library not loaded: /usr/lib/libSystem.B.dylib`. iPhone17,3's 27.0.1 cache (`0x17D508000`) still fits.
+
+The patch widens the arm64 region to `0x1C0000000`, the largest size that stays under the 26.4 kernel's own task-map ceilings. When the machine's kernel carries the patch (its `PatchReceipt.plist` says so), `cfw install` measures the cache against the widened region, so these devices install and boot; this was validated on iPhone18,2 27.0.1 as above.
+
+Without the patch (an older bundle, or the patch unticked), `cfw install` refuses such a cache with this explanation instead of leaving a guest that panics. Use iPhone17,3 for iOS 27, or iOS 26 on these devices.
## iPadOS
-See [iPadOS guests](ipados.md).
+iPad guests are described in [iPadOS guests](ipados.md).
| Host | iPad restore IPSW | PCC/cloudOS IPSW | Observed result |
| --- | --- | --- | --- |
@@ -131,7 +131,7 @@ See [iPadOS guests](ipados.md).
## Earlier reported combinations
-The previous README recorded the following host and firmware pairings. They predate the current single-mode flow or lack the same vphoned acceptance evidence, so treat them as research history rather than the current support matrix.
+An earlier README recorded these host and firmware pairings. They predate the current single-mode flow or lack the same vphoned acceptance evidence, so treat them as research history, not as the current support matrix.
| Host | iPhone | CloudOS |
| --------------- | --------------------- | --------------- |
@@ -155,3 +155,12 @@ The previous README recorded the following host and firmware pairings. They pred
| Mac16,11 27.0b2 | `17,3_27.0_24A5424a` | `26.4-23E5207q` |
| Mac16,11 27.0b2 | `17,3_27.0_24A5430a` | `26.4-23E5207q` |
| Mac16,6 26.6.1 | `17,3_27.0_24A435` | `26.4-23E5207q` |
+
+For the full list of patches and where each applies, see the [patch inventory](../../../Research/0_binary_patch_comparison.md).
+
+## See also
+
+- [Firmware preparation](firmware-preparation.md)
+- [Other iPhone models](iphone-models.md)
+- [iPadOS guests](ipados.md)
+- [Create and run a machine](../machines/create-and-run.md)
diff --git a/Documents/en/firmware/firmware-preparation.md b/Documents/en/firmware/firmware-preparation.md
new file mode 100644
index 00000000..df92d341
--- /dev/null
+++ b/Documents/en/firmware/firmware-preparation.md
@@ -0,0 +1,71 @@
+# Firmware preparation
+
+What `vm create` and `fw prepare` do with the two IPSWs before the firmware is patched, and the extra steps a cloudOS without vphone600 components needs. Read it when you run the stages by hand, reuse a GPU driver, or create a machine on a research-board pairing.
+
+## The GPU driver
+
+`fw prepare` needs the paravirtual GPU driver from the cloudOS before it can build the hybrid iPhone restore. It gets it like this:
+
+1. It creates a temporary vphone VM with no network device and starts it in DFU.
+2. It restores the selected cloudOS IPSW into it with vphone's own restore backend.
+3. It mounts the restored System volume read-only and extracts the GPU bundle.
+4. It removes the temporary VM.
+
+The extracted bundle is cached per cloudOS build in `~/.vphone/gpu-drivers/`, so later machines on the same cloudOS skip the temporary restore.
+
+To reuse a bundle you extracted earlier, pass it to `vm create` or `fw prepare`:
+
+```sh
+vphone-cli fw prepare myphone \
+ --gpu-driver-bundle /path/to/AppleParavirtGPUMetalIOGPUFamily.bundle
+```
+
+The CLI checks the bundle's iPhoneOS platform version against the selected cloudOS version. Each restore obtains its own ticket online.
+
+The bundle also ships an arm64e GPU compiler plugin. `fw prepare` copies it into the staged GPU bundle before patching and installation.
+
+## Research-board pairings
+
+A cloudOS after the 26.4 beta has no vphone600 components, so the research board stands in (see [Compatibility](compatibility.md#which-cloudos-to-use)). Its kernelcache is rebuilt with the vphone600 virtualization kexts. KDK extraction runs natively as you; only the kmutil link needs root.
+
+1. Run `fw prepare` as usual.
+2. Stage the mix as yourself:
+
+ ```sh
+ vphone-cli fw kernelcache myphone
+ ```
+
+3. Link it as root:
+
+ ```sh
+ sudo vphone-cli fw kernelcache myphone
+ ```
+
+4. Continue with `fw patch`, which takes the mix from the cache.
+
+The old `--ipsw` argument of `fw kernelcache` is still accepted but ignored.
+
+## Linking on another Mac
+
+A kernel boots only in the layout Apple linked it with, and kmutil takes the layout from the Mac it runs on:
+
+| Host macOS | Links |
+| --- | --- |
+| macOS 26.4 and later | iOS 26.4 and later kernelcaches (kernel-last) |
+| macOS 15, and 26.0 to 26.3 | older kernelcaches (kernel-first), such as iOS 18 |
+
+When this Mac has the other layout, another Mac or a macOS VM links the mix over ssh. Set these for `fw kernelcache` or for the creation:
+
+```sh
+export VPHONE_KMUTIL_SSH='user@host'
+export VPHONE_KMUTIL_SSH_PASSWORD='password' # only without ssh keys and passwordless sudo there
+```
+
+The staged volume is uploaded to that Mac's `/private/var/tmp`, linked there as root, and removed. Nothing on this Mac needs root for it. On the other Mac, Remote Login must be on, and the user must be allowed to use sudo.
+
+## See also
+
+- [Firmware compatibility](compatibility.md)
+- [Create and run a machine](../machines/create-and-run.md)
+- [Library, firmware and backups](../storage/library-and-backups.md)
+- [Kernelcache recipes](../../../VPhoneExecutable/VPhoneVirtualization/Resources/kernelcache_recipes/README.md)
diff --git a/Documents/en/firmware/ipados.md b/Documents/en/firmware/ipados.md
new file mode 100644
index 00000000..0fbdec36
--- /dev/null
+++ b/Documents/en/firmware/ipados.md
@@ -0,0 +1,96 @@
+# iPadOS guests
+
+How to run iPadOS instead of iOS in a vphone machine. Use it when you need an iPad's userland, screen size or multitasking features.
+
+The virtual hardware does not change: the boot chain, kernel, SEP and device tree still come from the PCC cloudOS IPSW (`vresearch101ap` / `vphone600ap`). Only the userland comes from an iPad's restore IPSW instead of the iPhone17,3's, and the device tree is rewritten so that the userland sees an iPad.
+
+![iPadOS home screen in a vphone VM](../../ipados-demo.jpeg)
+
+## Create one
+
+### In Launchpad
+
+1. Choose **New Machine**.
+2. Pick the iPad under **Device** and a release under **iPadOS**. The recommended cloudOS comes with it.
+3. For an IPSW that is not in the catalog, set **Source** to **Custom IPSWs**, put the iPad IPSW in the **iPhone IPSW** field and the cloudOS IPSW in the other.
+
+The **Device** menu appears only with a Core Bundle whose catalog lists iPads. From a terminal, `vphone-launchpad-cli vm create <name> --device iPad16,1` does the same.
+
+### With vphone-cli
+
+Pass the iPad restore IPSW where the iPhone one would go. The cloudOS is the same one an iPhone guest of that release would use.
+
+```sh
+vphone-cli vm create ipad-mini \
+ --iphone-source 'https://updates.cdn-apple.com/2026SummerFCS/cf7db64d-5866-4bf2-bfff-50a32f58bec3/iPad16,1,iPad16,2_26.6.2_23G90_Restore.ipsw' \
+ --cloudos-source 'https://updates.cdn-apple.com/private-cloud-compute/c0ecdb4b310cf5239ab2b248dd3098eec297dc5aa3bbe6ada27273262b0b8b64'
+
+# The 13-inch iPad Pro (M5), from the IPSW that also carries the 11-inch
+vphone-cli vm create ipad-pro-13 --device iPad17,3 \
+ --iphone-source 'https://updates.cdn-apple.com/2026SummerFCS/<…>/iPad17,1,iPad17,2,iPad17,3,iPad17,4_26.6.2_23G90_Restore.ipsw' \
+ --cloudos-source 'https://updates.cdn-apple.com/private-cloud-compute/c0ecdb4b310cf5239ab2b248dd3098eec297dc5aa3bbe6ada27273262b0b8b64'
+```
+
+To find a release:
+
+| Command | Lists |
+| --- | --- |
+| `vphone-cli fw catalog` | Every supported iPad's iPadOS releases, each with its cloudOS |
+| `vphone-cli fw catalog --device iPad16,1` | One iPad's releases |
+| `vphone-cli fw prepare --device iPad16,1 --list` | The iPad's downloadable IPSWs |
+| `vphone-cli fw prepare --device iPad16,1 --iphone-version 26.6.2` | Resolves one IPSW |
+
+With `--device` and no sources, `vm create` offers that iPad's releases to choose from.
+
+### Pick the model in a shared IPSW
+
+Most iPad IPSWs cover several models; the iPad Air and iPad Pro IPSWs carry both sizes. Without `--device`, `fw prepare` takes the first model the IPSW lists (the 11-inch). Pass `--device iPad17,3` to `fw prepare` or `vm create` for the 13-inch. Launchpad's New Machine passes the model chosen under **Device**; with **Custom IPSWs** it takes the first.
+
+<img src="../../ipados/ipad-pro-13-home.jpg" alt="iPad Pro 13-inch home screen in a vphone VM" width="360" />
+
+### Manual stages
+
+The manual stages are the same as for an iPhone guest: `vm new`, `fw prepare`, `fw patch`, DFU and `restore`, `cfw install`, `vm launch`. Only `fw prepare` and `fw patch` behave differently for an iPad; DFU, `restore` and `cfw install` run unchanged.
+
+## Supported devices
+
+| Product | Model | Board | Panel | Points @2x |
+| --- | --- | --- | --- | --- |
+| `iPad16,1` | iPad mini (A17 Pro) | J410AP | 1488x2266 @ 326 ppi | 744x1133 |
+| `iPad15,7` | iPad (A16) | J481AP | 1640x2360 @ 264 ppi | 820x1180 |
+| `iPad15,3` | iPad Air 11-inch (M3) | J607AP | 1640x2360 @ 264 ppi | 820x1180 |
+| `iPad15,5` | iPad Air 13-inch (M3) | J637AP | 2048x2732 @ 264 ppi | 1024x1366 |
+| `iPad16,3` | iPad Pro 11-inch (M4) | J717AP | 1668x2420 @ 264 ppi | 834x1210 |
+| `iPad16,5` | iPad Pro 13-inch (M4) | J720AP | 2064x2752 @ 264 ppi | 1032x1376 |
+| `iPad17,1` | iPad Pro 11-inch (M5) | J817AP | 1668x2420 @ 264 ppi | 834x1210 |
+| `iPad17,3` | iPad Pro 13-inch (M5) | J820AP | 2064x2752 @ 264 ppi | 1032x1376 |
+
+The cellular models (`iPad16,2`, `iPad15,4`, `iPad15,6`, `iPad16,4`, `iPad16,6`, `iPad17,2`, `iPad17,4`) share their Wi-Fi twin's IPSW and run as it: the VM has no baseband. `iPad15,8` ships in an IPSW of its own without the Wi-Fi board and is not supported.
+
+Tested pairings are in [Compatibility](compatibility.md#ipados).
+
+## What changes for an iPad
+
+- **`fw prepare`** recognizes the IPSW from its `SupportedProductTypes`, takes the erase identity and `DeviceMap` entry for the guest's board (an iPad IPSW covers several), and records the product type and the iPad's display in the machine's `config.plist` (`guestProductType`, `screenConfig`). The restore tree is named `iPhoneOS_iPad16,1_<version>_<build>_Restore`; the `iPhone` prefix is the restore-tree convention every reader matches, not the device.
+- **Two device trees.** The hybrid manifest normally points `DeviceTree` and `RestoreDeviceTree` at the same vphone600 file. For an iPad, `DeviceTree` points at a copy, `Firmware/all_flash/DeviceTree.vphone600ap.guest.im4p`. Restore boots the untouched identity that `restored_external` checks against the manifest (`iPhone99,11`); the guest boots the copy.
+- **`fw patch`** gives that copy the iPad's identity and presentation (patch set `devicetree`, entries `devicetree-cfw-ipad_*`):
+ - root `model`, `target-type` and `target-sub-type` as on the board (for the iPad mini `iPad16,1`, `J410`, `J410AP`), and `compatible` with the board first and `VPHONE600AP` kept second;
+ - `/product`: the board's artwork idiom, subtype and scale, product name, chrome, camera and button geometry, multitasking capabilities (`medusa-overlay-app-capability`, `ui-floating-live-app`, `ui-overlay-app`, `ui-pinned-app`, and `disable-chamois` where the board has no Stage Manager), and its product type and unique model, all read from the board's `DeviceTree.<board>.im4p`, which the restore tree keeps;
+ - phone-only `syscfg` placeholders (Dynamic Island, reachability, ringer switch, volume-button geometry, CarPlay, Watch pairing) are removed.
+
+ The virtual hardware keeps its vphone600 description: GPU feature set, framebuffer, memory class and boot flags.
+- **LLB** gets one more patch on an iPad guest, `llb-cfw-display_scale`. LLB fills `/chosen/display-scale` from the paravirtual display's boot video word, which always says 3x, and MobileGestalt turns that property into the screen scale, so an iPad would get a 496x755-point canvas. The patch makes LLB write the iPad's own scale (2x, 744x1133 points for the iPad mini).
+- **`cfw install`** leaves the installed device tree alone. The iPhone17,3 post-restore identity rewrite (`preboot-exp-devicetree_identity`) is skipped on an iPad guest.
+- **The machine window** follows `screenConfig`, so it opens at the iPad's aspect ratio.
+
+<img src="../../ipados/display-scale-3x-before.jpg" alt="iPad guest at 3x display scale, before the LLB patch" width="240" />
+
+## Adding another iPad
+
+Adding an iPad model takes one line in [`VPhoneGuestDevice`](../../../VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneGuestDevice.swift): its product type, board and panel. Everything the device tree needs is read from the board's own `DeviceTree.<board>.im4p` in the IPSW.
+
+## See also
+
+- [Other iPhone models](iphone-models.md)
+- [Firmware compatibility](compatibility.md)
+- [Create and run a machine](../machines/create-and-run.md)
diff --git a/Documents/en/firmware/iphone-models.md b/Documents/en/firmware/iphone-models.md
new file mode 100644
index 00000000..a5c0340f
--- /dev/null
+++ b/Documents/en/firmware/iphone-models.md
@@ -0,0 +1,67 @@
+# Other iPhone models
+
+How to run a guest whose iOS comes from another iPhone's restore IPSW instead of the iPhone17,3's (iPhone 16). Use it when you need a specific model's userland, panel size or identity.
+
+The virtual hardware stays the same, as with an [iPad guest](ipados.md): the boot chain, kernel, SEP and device tree still come from the PCC cloudOS IPSW (`vresearch101ap` / `vphone600ap`). Only the userland comes from the chosen model's IPSW, and the device tree the guest boots is rewritten to present that model.
+
+## Create one
+
+In Launchpad, choose **New Machine**, pick the model under **Device** and a release under **iOS**.
+
+From a terminal, through Launchpad:
+
+```sh
+vphone-launchpad-cli vm create iphone17pro --device iPhone18,1
+```
+
+With `vphone-cli`, pass the model's IPSW and the cloudOS:
+
+```sh
+vphone-cli vm create iphone17pro \
+ --iphone-source 'https://updates.cdn-apple.com/2026SummerFCS/f768ecdf-e037-44e6-bfa6-949b6d127c4f/iPhone18,1_26.6.2_23G90_Restore.ipsw' \
+ --cloudos-source 'https://updates.cdn-apple.com/private-cloud-compute/c0ecdb4b310cf5239ab2b248dd3098eec297dc5aa3bbe6ada27273262b0b8b64'
+```
+
+Each iPhone model has an IPSW of its own, so `--device` is not needed with explicit sources.
+
+To find a release, run `fw catalog`. It lists the iPhone 16 and 17 models' releases from 26.0 to 27.0.1 (the iPhone 17e from 26.3.1) and the iPhone 18 Pro's 27.0.1, each with the cloudOS an iPhone17,3 of that release uses. To list one model's releases:
+
+```sh
+vphone-cli fw catalog --device iPhone18,1
+```
+
+## Supported devices
+
+| Product | Model | Board | Panel | Points @3x |
+| --- | --- | --- | --- | --- |
+| `iPhone17,3` | iPhone 16 | D47AP | 1290x2796 @ 460 ppi | 430x932 |
+| `iPhone17,4` | iPhone 16 Plus | D48AP | 1290x2796 @ 460 ppi | 430x932 |
+| `iPhone17,1` | iPhone 16 Pro | D93AP | 1206x2622 @ 460 ppi | 402x874 |
+| `iPhone17,2` | iPhone 16 Pro Max | D94AP | 1320x2868 @ 460 ppi | 440x956 |
+| `iPhone17,5` | iPhone 16e | V59AP | 1170x2532 @ 460 ppi | 390x844 |
+| `iPhone18,3` | iPhone 17 | V57AP | 1206x2622 @ 460 ppi | 402x874 |
+| `iPhone18,4` | iPhone Air | D23AP | 1260x2736 @ 460 ppi | 420x912 |
+| `iPhone18,1` | iPhone 17 Pro | V53AP | 1206x2622 @ 460 ppi | 402x874 |
+| `iPhone18,2` | iPhone 17 Pro Max | V54AP | 1320x2868 @ 460 ppi | 440x956 |
+| `iPhone18,5` | iPhone 17e | V159AP | 1170x2532 @ 460 ppi | 390x844 |
+| `iPhone19,2` | iPhone 18 Pro | V63AP | 1206x2622 @ 460 ppi | 402x874 |
+
+Every model, the iPhone17,3 included, gets its panel and identity from its own device tree; the iPhone17,3's panel is the display it has always had.
+
+The iPhone 17 Pro, 17 Pro Max and 18 Pro have recorded boot validation; see [Compatibility](compatibility.md#other-iphone-models). The iPhone 17 Pro and 17 Pro Max need a patch on iOS 27, described there.
+
+> [!WARNING]
+> iPhone19,2 uses ARM64E_X1. On hosts without native X1 support, the standard preset lowers the unsupported instructions, which weakens PC-bound pointer authentication.
+
+## What changes for another iPhone
+
+Everything listed under [What changes for an iPad](ipados.md#what-changes-for-an-ipad) applies, with two differences:
+
+- The board's `/product` values replace the vphone600 placeholders the same way, but an iPhone board keeps its phone properties: Dynamic Island, reachability, OLED, volume-button geometry, CarPlay and Watch pairing come from the board instead of being removed. The patch IDs are the `devicetree-cfw-ipad_*` ones; they were named before iPhones used them.
+- LLB is not patched for the display scale. The paravirtual display's boot video word says 3x, which is already an iPhone's scale.
+
+## See also
+
+- [iPadOS guests](ipados.md)
+- [Firmware compatibility](compatibility.md)
+- [Create and run a machine](../machines/create-and-run.md)
diff --git a/Documents/Downloads/README.md b/Documents/en/get-started/downloads.md
similarity index 68%
rename from Documents/Downloads/README.md
rename to Documents/en/get-started/downloads.md
index 5599da76..dde63043 100644
--- a/Documents/Downloads/README.md
+++ b/Documents/en/get-started/downloads.md
@@ -1,5 +1,9 @@
# Downloads
+Pick the Launchpad version to download and the `VPhone.bundle` that goes with it. Use this page when the latest release has no notarized Launchpad, or when you need to match versions by hand.
+
+## What each release contains
+
Each [release](https://github.com/Lakr233/vphone-cli/releases) has up to three files:
| File | Contents |
@@ -8,7 +12,9 @@ Each [release](https://github.com/Lakr233/vphone-cli/releases) has up to three f
| `vphone-launchpad-<version>.zip` | Launchpad, not notarized. macOS blocks it the first time you open it. |
| `VPhone-<version>.zip` | `VPhone.bundle`. Launchpad downloads and installs it for you, so you do not need this file. |
-## Notarized Launchpad Versions
+To open a version that is not notarized, open it once, then go to **System Settings > Privacy & Security** and click **Open Anyway**.
+
+## Notarized Launchpad versions
| Series | Notarized | Not Notarized |
| --- | --- | --- |
@@ -31,8 +37,6 @@ Each [release](https://github.com/Lakr233/vphone-cli/releases) has up to three f
There is no 2.0.7 or 2.10.0 release.
-To open a version that is not notarized, open it once, then go to **System Settings > Privacy & Security** and click **Open Anyway**.
-
## Matching Launchpad and VPhone.bundle
Use a `VPhone.bundle` from the same series as Launchpad. The series is the first two numbers of the version: Launchpad 2.2.3 belongs to 2.2 and works with any `VPhone.bundle` 2.2.x.
@@ -58,15 +62,25 @@ Use a `VPhone.bundle` from the same series as Launchpad. The series is the first
Within a series, install the newest `VPhone.bundle`. Patch releases fix problems without changing how Launchpad and the bundle work together.
-Series 2.15 adds HomeView. Use Launchpad 2.15 with its bundle so New Machine
-selects the `homeview` preset for `HomeAccessory17,1` and `HomeAccessory17,2`.
+Launchpad refuses a `VPhone.bundle` that is too old for it, but it may still list bundles from a newer series. Do not install those; update Launchpad to that series first.
+
+> [!NOTE]
+> Launchpad does not update itself. Download the new version from the release page and replace the old app.
-Series 2.14 lets a machine use a patch preset from a file: Other… in the
-preset picker, or `--preset <path>`. Launchpad 2.14 needs a 2.14 bundle.
+## What recent series add
-Series 2.13 adds Apple TV 4K (4th generation). Use Launchpad 2.13 with its
-bundle so New Machine selects the `tvos-4k` preset for `AppleTV18,1`.
+| Series | Adds | Note |
+| --- | --- | --- |
+| 2.15 | HomeView | Use Launchpad 2.15 with its bundle so New Machine selects the `homeview` preset for `HomeAccessory17,1` and `HomeAccessory17,2`. |
+| 2.14 | Patch presets from a file: **Other…** in the preset picker, or `--preset <path>` | Launchpad 2.14 needs a 2.14 bundle. |
+| 2.13 | Apple TV 4K (4th generation) | Use Launchpad 2.13 with its bundle so New Machine selects the `tvos-4k` preset for `AppleTV18,1`. |
-Launchpad refuses a `VPhone.bundle` that is too old for it, but it may still list bundles from a newer series. Do not install those; update Launchpad to that series first. Launchpad does not update itself: download the new version from the release page and replace the old app.
+## Version 1.x
VMs created by 1.x do not start in 2.x. For 1.x, see the [1.0.14 release](https://github.com/Lakr233/vphone-cli/releases/tag/1.0.14).
+
+## See also
+
+- [Quick Start](quick-start.md)
+- [Core Bundles](../launchpad/core-bundles.md)
+- [Launchpad Command Line](../launchpad/launchpad-cli.md)
diff --git a/Documents/en/get-started/host-setup.md b/Documents/en/get-started/host-setup.md
new file mode 100644
index 00000000..2e0cbf8c
--- /dev/null
+++ b/Documents/en/get-started/host-setup.md
@@ -0,0 +1,112 @@
+# Host Setup
+
+Prepare your Mac so it can run the entitled VM process, `vphone-vm`. Do this once per Mac, and repeat the allowlist step whenever the `vphone-vm` signature changes.
+
+You need an Apple Silicon Mac running macOS 15 or newer. PV=3 research guests do not run inside a nested macOS VM.
+
+## Check the host
+
+Run the preflight from the `VPhone.bundle` you use:
+
+```sh
+vphone-cli host preflight
+```
+
+It checks the entitled `vphone-vm` before any VM starts. If AMFI refuses `vphone-vm`, the error prints the exact `sudo .../vphone-escalator allow .../vphone-vm` command for that bundle.
+
+## Choose a security configuration
+
+`vphone-vm` carries Apple-private virtualization entitlements, so macOS must accept it. Both options below need Research Guests enabled in Recovery. Choose one.
+
+### Option A: Keep SIP enabled with debugging restrictions relaxed
+
+1. Boot into macOS Recovery, open Terminal, and run:
+
+ ```sh
+ csrutil enable --without debug
+ csrutil allow-research-guests enable
+ ```
+
+2. Restart into macOS.
+3. Allowlist the current `vphone-vm`. With a distributed bundle, run `vphone-cli host preflight` and run the command it prints. From a source checkout:
+
+ ```sh
+ bundle=.build/XcodeBundle/Build/Products/Debug/VPhone.bundle
+ sudo "$bundle/Contents/MacOS/vphone-escalator" allow "$bundle/Contents/MacOS/vphone-vm"
+ "$bundle/Contents/MacOS/vphone-escalator" status
+ "$bundle/Contents/MacOS/vphone-cli" host preflight
+ ```
+
+> [!WARNING]
+> Repeat the `allow` command after every build, including a rebuild that only changes the signature. The allowlist holds the `vphone-vm` cdhash, and a new signature has a new one.
+
+To undo the allowlist:
+
+```sh
+sudo "$bundle/Contents/MacOS/vphone-escalator" off
+```
+
+`off` removes only the hashes `vphone-escalator` added and restarts amfid. It keeps the preference and its other values.
+
+You can pass more signed host binaries to the same `allow` command when they need restricted entitlements. The unentitled `vphone-cli` does not need it.
+
+### Option B: Disable SIP and AMFI
+
+This is the more permissive configuration.
+
+1. Boot into macOS Recovery, open Terminal, and run:
+
+ ```sh
+ csrutil disable
+ csrutil allow-research-guests enable
+ ```
+
+2. Restart into macOS, set the boot argument, and restart again:
+
+ ```sh
+ sudo nvram boot-args="amfi_get_out_of_my_way=1 -v"
+ ```
+
+> [!WARNING]
+> This replaces any existing `boot-args`. Check them with `nvram boot-args` first.
+
+## With Launchpad
+
+Launchpad's bundle preflight checks that SIP debugging restrictions are disabled (or SIP is fully disabled) and that Research Guests is enabled. You do not run `vphone-escalator` yourself:
+
+- If AMFI blocks the installed `vphone-vm`, Launchpad's helper checks those host settings again, verifies the root-owned bundle and its recorded cdhash, runs that bundle's `vphone-escalator allow` as root, and Launchpad repeats preflight.
+- Each new bundle signature is checked and allowed separately.
+- When a newer Launchpad includes a newer helper, it asks for administrator authorization to update the helper at startup.
+
+The standalone `vphone-cli` still reports the manual command.
+
+## Build from source
+
+A distributed `VPhone.bundle` needs no Homebrew, Python, or Xcode at runtime. Building from source needs Xcode and its iPhoneOS SDK, which compiles `vphoned`. From a checkout:
+
+```sh
+xcodebuild -workspace VPhone.xcworkspace -scheme VPhone \
+ -configuration Debug -destination 'platform=macOS,arch=arm64' \
+ -derivedDataPath .build/XcodeBundle build
+.build/XcodeBundle/Build/Products/Debug/VPhone.bundle/Contents/MacOS/vphone-cli host preflight
+```
+
+The `VPhone` scheme produces the ad hoc signed bundle with all its programs. With Option A, allowlist each new build.
+
+## What the allowlist changes
+
+`vphone-escalator allow` creates the AMFI code-requirements preference if it is absent. If it exists, it appends the current `vphone-vm` cdhash to its `Entitlements` requirement, keeping other cdhashes and preference keys, and skips hashes already there. It leaves an existing `AllowUnsafeDynamicLinking` value untouched and writes `false` only when that key is absent. It makes amfid consult the requirement by changing one byte in amfid's heap.
+
+## What the bundle contains
+
+- `vphone-cli` orchestrates the work without private entitlements and handles archives through `vphone-cli archive`.
+- `vphone-vm` is the signed, entitled VM and window process.
+- `vphoned` is compiled for iOS at build time and installed into each created guest.
+
+For the implementation history, see the [research notes on the binary split](../../../Research/Host/host_binary_split.md).
+
+## See also
+
+- [Quick Start](quick-start.md)
+- [Create and Run a VM](../machines/create-and-run.md)
+- [Troubleshooting](../help/troubleshooting.md)
diff --git a/Documents/en/get-started/overview.md b/Documents/en/get-started/overview.md
new file mode 100644
index 00000000..4da9ce06
--- /dev/null
+++ b/Documents/en/get-started/overview.md
@@ -0,0 +1,50 @@
+# Overview
+
+vphone-cli runs a virtual iPhone on an Apple Silicon Mac. Read this page to learn what it does, what your Mac needs, and which program does what.
+
+> [!WARNING]
+> This project has never issued or authorized any cryptocurrency or token, and does not accept cryptocurrency payments or donations. Any cryptocurrency or token issued or promoted in this project's name, or claiming any affiliation with it, is a scam.
+
+![Virtual iPhone running on macOS](../../demo.jpeg)
+
+vphone-cli runs iOS with Apple's Virtualization.framework and PCC research virtual machines, for security research, reverse engineering, and debugging.
+
+## Features
+
+- **Graphical window:** Use the virtual iPhone's screen on your Mac, browse apps and files, and take screenshots and screen recordings.
+- **Custom firmware:** The system comes pre-patched, and you can install a [package environment](../machines/package-environment.md).
+- **Backup and cloning:** Export, import, and clone VMs.
+- **Automation API:** An optional local HTTP and WebSocket interface. See [Automation API](../machines/automation-api.md).
+- **No extra dependencies:** Needs no Xcode, Python, or Homebrew at runtime.
+
+## Requirements
+
+- A physical Apple Silicon Mac running macOS 15 or newer. It does not work in a macOS VM.
+- Free disk space. Each VM has a 64 GB virtual disk by default, and firmware takes more.
+- A network connection. Restoring the system fetches signing tickets online.
+- Adjusted security settings. Boot into macOS Recovery, run these commands in Terminal, then restart:
+
+ ```sh
+ csrutil enable --without debug
+ csrutil allow-research-guests enable
+ ```
+
+ SIP stays enabled, with only the debugging restrictions relaxed. For details, see [Host Setup](host-setup.md).
+
+## The four programs
+
+| Program | What it does |
+| --- | --- |
+| `vphone-launchpad` | A Mac app that downloads and installs `VPhone.bundle` and sets up the host. Released separately. |
+| `vphone-cli` | Prepares firmware, patches it, restores the system, and manages VMs. |
+| `vphone-vm` | Runs the VM and shows its window. |
+| `vphoned` | The control service inside the VM. The window's features and the API work through it. |
+
+`vphone-cli`, `vphone-vm` and `vphoned` ship together in `VPhone.bundle`. Launchpad drives each VM through the `vphone-cli` inside that bundle; you can also run `vphone-cli` yourself in Terminal.
+
+## See also
+
+- [Quick Start](quick-start.md)
+- [Host Setup](host-setup.md)
+- [Downloads](downloads.md)
+- [Create and Run a VM](../machines/create-and-run.md)
diff --git a/Documents/en/get-started/quick-start.md b/Documents/en/get-started/quick-start.md
new file mode 100644
index 00000000..bb0879e9
--- /dev/null
+++ b/Documents/en/get-started/quick-start.md
@@ -0,0 +1,41 @@
+# Quick Start
+
+Set up vphone with Launchpad and boot your first virtual iPhone. Do this once your Mac meets the [requirements](overview.md#requirements).
+
+## Set up with Launchpad
+
+1. Download `vphone-launchpad-<version>-notarized.zip` from the [latest release](https://github.com/Lakr233/vphone-cli/releases/latest), unzip it, and open it. Not every release is notarized. If the latest one has no `-notarized` file, pick a notarized version from [Downloads](downloads.md).
+2. In **Host Setup**, grant Developer Tools access and install the helper.
+3. In **Core Bundle**, click **Download and Install**.
+4. In **Machines**, click **New Machine**, choose a firmware pairing, and click **Create**.
+
+Launchpad downloads the firmware, patches it, restores the system, and boots the VM. To use your own iPhone and cloudOS IPSWs, see [Compatibility](../firmware/compatibility.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.
+```
+
+## Next steps
+
+- Install a package manager in the VM: [Package Environment](../machines/package-environment.md).
+- Drive VMs from Terminal, or create one without Launchpad: [Create and Run a VM](../machines/create-and-run.md).
+- Script the VM over HTTP and WebSocket: [Automation API](../machines/automation-api.md).
+- Something went wrong: [Troubleshooting](../help/troubleshooting.md).
+
+## See also
+
+- [Host Setup](host-setup.md)
+- [Downloads](downloads.md)
+- [Launchpad Command Line](../launchpad/launchpad-cli.md)
diff --git a/Documents/en/help/troubleshooting.md b/Documents/en/help/troubleshooting.md
new file mode 100644
index 00000000..58e7dbc3
--- /dev/null
+++ b/Documents/en/help/troubleshooting.md
@@ -0,0 +1,52 @@
+# Troubleshooting
+
+Find the symptom or error message you see, then follow the fix under it. For network problems, see [Networking](../networking/overview.md).
+
+## `vphone-vm` is killed before the VM opens
+
+1. Run the host preflight:
+
+ ```sh
+ vphone-cli host preflight
+ ```
+
+ The CLI is unentitled, so it keeps running and can explain an AMFI refusal of its signed `vphone-vm` companion.
+2. If you rebuilt the bundle, the cdhash changed. Allow the new binaries with the bundled helper as described in [Host setup](../get-started/host-setup.md).
+
+## `Virtualization is not available on this hardware`
+
+PV=3 guests cannot be nested. Boot on an Apple Silicon Mac, not inside another macOS VM.
+
+## `vm create` printed vphoned success, but no VM is running
+
+That is expected. Creation starts a temporary GUI boot, sends a real ping, and stops that boot before returning. Start the VM for use:
+
+```sh
+vphone-cli vm launch <name>
+```
+
+## Stuck at "Press home to continue"
+
+Click the Home button in the VM window's title bar. The current JB workflow does not install a VNC server.
+
+## App exits with `EXC_GUARD` / `GUARD_TYPE_MACH_PORT`
+
+The kernel patch `kernel-boot-thread_guard_violation` stops fatal Mach port guard delivery. It applies only on an iOS 18 base, where it is needed to boot, and every preset turns it on there. Other bases cannot select it, so an app that trips this guard on a 26.x base still exits. See [issue #291](https://github.com/Lakr233/vphone-cli/issues/291).
+
+## Restore or first boot fails
+
+- In a manual flow, keep the VM in DFU until `restore` exits.
+- Check that online ticket requests can reach Apple.
+- For the complete pipeline, rerun `vm create` with a **new name** and `-v` for tool detail.
+- Avoid creating VMs in parallel when memory or disk is tight.
+- Before combining an iPhone IPSW with a PCC image, check [Firmware compatibility](../firmware/compatibility.md).
+
+## The guest boots, but vphoned does not answer during creation
+
+The first-boot check times out after 300 seconds. Creation uses a GUI boot because a newly restored guest may not bring up vphoned during its first headless boot. See [Create and run](../machines/create-and-run.md) for what the success marker proves.
+
+## See also
+
+- [Host setup](../get-started/host-setup.md)
+- [Create and run](../machines/create-and-run.md)
+- [Firmware compatibility](../firmware/compatibility.md)
diff --git a/Documents/en/launchpad/bundle-integration.md b/Documents/en/launchpad/bundle-integration.md
new file mode 100644
index 00000000..de34b63f
--- /dev/null
+++ b/Documents/en/launchpad/bundle-integration.md
@@ -0,0 +1,59 @@
+# VPhone bundle integration
+
+This page is for anyone building an application that ships or drives `VPhone.bundle`, as `vphone-launchpad` does. It describes what the bundle contains and what the integrating application is responsible for.
+
+## Build and validate
+
+```sh
+xcodebuild -workspace VPhone.xcworkspace -scheme VPhone \
+ -configuration Debug -destination 'platform=macOS,arch=arm64' \
+ -derivedDataPath .build/XcodeBundle build
+```
+
+The `VPhone` scheme produces `VPhone.bundle`, and `ValidateBundle.sh` checks it as part of the build.
+
+## How to integrate
+
+- Keep the bundle intact and launch `Contents/MacOS/vphone-cli` as a process. The bundle is a container for executables and resources, not a macOS app or a dynamically loaded plug-in. The CLI locates its companion `vphone-vm` by resolving its own executable path.
+- Install and update the whole bundle as one versioned unit. Do not rewrite a signed binary in place.
+- When `vphone-vm` changes, its cdhash changes. Arrange AMFI admission for the new build before launching it.
+- Your application owns download, release verification, host authorization, installation and update policy. Developer Tools access and AMFI authorization are separate host decisions.
+- The VM library and caches stay outside `VPhone.bundle`, under `~/.vphone` by default. Host-side VM outputs use mode `0777` so a separate workstation process can access them, including after a root-run create. Guest filesystem permissions inside `Disk.img` keep their own semantics.
+
+## Bundle contents
+
+| Path | Role |
+| --- | --- |
+| `Contents/MacOS/vphone-cli` | Unentitled command entry point |
+| `Contents/MacOS/vphone-vm` | VM and window process; private virtualization entitlements |
+| `Contents/MacOS/vphone-escalator` | AMFI allowlist tool for the current VM cdhash |
+| `Contents/MacOS/libswiftCompatibilitySpan.vphone.dylib` | Swift back-deployment library for `vphone-vm` on macOS 15 |
+| `Contents/Resources/guest-resources/vphoned` | Pre-signed guest daemon with its own entitlements; the bundle contains no unsigned copy |
+| `Contents/Resources/guest-resources/*.dylib` | Guest libraries: launchd hook, SystemHook, camera hooks, the GPU compiler plugin, and the fixes and device adapters listed in [`VPhoneGuestComponents`](../../../VPhoneGuestComponents/README.md) |
+| `Contents/Resources/guest-resources/*.plist` | Guest launch daemon configuration, camera hook and MISFix filters |
+| `Contents/Resources` | Localized strings; no signing script or entitlement file is shipped |
+
+`Contents/MacOS` holds only programs that run on the Mac. `guest-resources` holds only files installed into the guest, and every Mach-O in it is built for iOS. `ValidateBundle.sh` enforces both rules.
+
+## Signing
+
+All executable payloads use ad hoc code signatures. Only the child processes that need them carry private entitlements. The bundle has no `CFBundleExecutable`, app launcher, SMJobBless helper, installer, password prompt, or automatic root acquisition.
+
+## Privacy permissions
+
+macOS asks for a privacy permission (microphone, location) on behalf of the responsible process and ties the grant to that process's code signature.
+
+- If you start `vphone-cli` with responsibility disclaimed, it becomes the responsible process for `vphone-vm`. It is signed ad hoc, so each new bundle build is asked again.
+- If you start `vphone-cli` as an ordinary child of a process with a stable signature, without disclaiming responsibility, the permission is asked once.
+
+Launchpad does the second with `vphone-launchpad-launcher`, which it carries in its own `Contents/MacOS`. macOS attributes a tool there to the enclosing app, so the prompt, the usage description and the grant are the app's. Under the hardened runtime the app's main executable must carry the matching resource entitlement (`com.apple.security.device.audio-input`, `com.apple.security.personal-information.location`); without it macOS refuses the request without asking.
+
+## Version compatibility
+
+Launchpad refuses a bundle older than `minimumBundleComponents` (set in [`VPhoneLaunchpad/VPhoneLaunchpadShared/VPhoneLaunchpadBundleStore.swift`](../../../VPhoneLaunchpad/VPhoneLaunchpadShared/VPhoneLaunchpadBundleStore.swift)) and does not load older bundle layouts. Bundle 2.1.0 added patch presets (`fw patches`, `fw set-patches`, `fw patch --preset`) and the `vphone-escalator` executable.
+
+## See also
+
+- [Core Bundles and local builds](core-bundles.md)
+- [Launchpad command line](launchpad-cli.md)
+- [Host setup](../get-started/host-setup.md)
diff --git a/Documents/en/launchpad/core-bundles.md b/Documents/en/launchpad/core-bundles.md
new file mode 100644
index 00000000..da3919b9
--- /dev/null
+++ b/Documents/en/launchpad/core-bundles.md
@@ -0,0 +1,104 @@
+# Core Bundles and local builds
+
+Each Launchpad machine runs with one installed `VPhone.bundle` version, its Core Bundle. This page shows how to install a local build, move a machine to it, and compare two builds side by side.
+
+## Test a VPhone.bundle build
+
+1. Build the bundle from the repository root:
+
+ ```sh
+ xcodebuild -workspace VPhone.xcworkspace -scheme VPhone \
+ -configuration Debug -destination 'platform=macOS,arch=arm64' \
+ -derivedDataPath .build/XcodeBundle build
+ ```
+
+2. Install it. It installs as `<version>-local.<hash>`, becomes the default, gets the execution policy exception, has the new `vphone-vm` cdhash allowed, and runs host preflight:
+
+ ```sh
+ vphone-launchpad-cli bundle install-local .build/XcodeBundle/Build/Products/Debug/VPhone.bundle
+ ```
+
+ The exact version is in the install result and in `bundle list`.
+
+3. Move an existing machine to it. `--update-environment` also redeploys the new vphoned and hook dylibs, and needs the machine to be stopped:
+
+ ```sh
+ vphone-launchpad-cli vm set-bundle research-01 2.4.0-local.1a2b3c4d --update-environment
+ ```
+
+4. Start the machine and check it:
+
+ ```sh
+ vphone-launchpad-cli vm start research-01 --wait
+ vphone-launchpad-cli guest rpc research-01 device.info
+ vphone-launchpad-cli guest rpc research-01 apps.list '{}'
+ vphone-launchpad-cli vm log research-01 --lines 100
+ vphone-launchpad-cli vm stop research-01
+ ```
+
+The helper's authorization lasts five minutes. The first step that needs the helper after it expires asks for an administrator password on the Mac, as the window does.
+
+For the one-time kernel and guest update that enables persistent shader caches on an existing VM, see [Persistent shader caches](../storage/shader-cache.md).
+
+## Compare two builds
+
+Install both without moving the default, then give each its own machine:
+
+```sh
+vphone-launchpad-cli bundle install-local /path/to/A/VPhone.bundle --keep-default
+vphone-launchpad-cli bundle install-local /path/to/B/VPhone.bundle --keep-default
+vphone-launchpad-cli bundle list # note both versions
+
+vphone-launchpad-cli vm create cmp-a --bundle 2.4.0-local.aaaaaaaa
+vphone-launchpad-cli vm create cmp-b --bundle 2.4.0-local.bbbbbbbb
+```
+
+Machines created this way differ in all three layers (see below). To compare only host programs and guest environment on one boot chain, clone a machine in the window and rebind the copy:
+
+```sh
+vphone-launchpad-cli vm set-bundle cmp-b 2.4.0-local.bbbbbbbb --update-environment
+```
+
+`vm list` shows which bundle each layer came from. `bundle remove` refuses a version while a machine is bound to it; rebind or delete those machines first.
+
+## How machines are bound to bundles
+
+Every machine is bound to one installed version, chosen when it is created and kept in `launchpad.json` in the machine folder. Installing a bundle never changes a machine's binding.
+
+A machine is made of three layers, each taken from a bundle at a different time:
+
+| Layer | What | Comes from |
+| --- | --- | --- |
+| Host Programs | `vphone-cli`, `vphone-vm` | The bound bundle, on every command. A new binding applies at the next start. |
+| Guest Environment | vphoned and the hook dylibs | `cfw install` at creation, and `cfw update-environment` (stopped machine) later. |
+| Boot Chain | Patched firmware, restore, CFW patches | `fw patch`, `restore` and `cfw install` at creation. |
+
+### Changing boot-chain patches later
+
+`vphone-cli fw set-patches` changes the patch choice, and `vphone-cli fw patches <vm>` lists what has not reached the guest yet. Launchpad shows the count in the inspector. Each kind of patch reaches the guest a different way:
+
+| Patch | Applies with |
+| --- | --- |
+| Guest patches | The next `cfw update-environment` |
+| AVPBooter | The next `fw patch` |
+| Kernel patches | `cfw update-kernel` (keeps the data, no restore tree needed) |
+| The rest of the boot chain (TXM, DeviceTree, LLB) | Only a restore, which erases the guest |
+
+## The default bundle
+
+The **default** bundle (formerly "active") decides only:
+
+- which version `vm create` binds when `--bundle` is not given;
+- what `exec` and library-wide commands run with.
+
+A new install becomes the default unless you pass `--keep-default`. The first start of a machine in a Launchpad session checks its bundle once (execution policy exception, AMFI, host preflight).
+
+## Version names
+
+Local builds install as `<version>-local.<hash>`, with the hash taken from the bundle's code-signature seal, so two builds of one version sit side by side. Older stores may still hold `<version>-local` or `<version>-ci.<commit>`.
+
+## See also
+
+- [Launchpad command line](launchpad-cli.md)
+- [Bundle integration](bundle-integration.md)
+- [Downloads](../get-started/downloads.md)
diff --git a/Documents/en/launchpad/launchpad-cli.md b/Documents/en/launchpad/launchpad-cli.md
new file mode 100644
index 00000000..0d90b604
--- /dev/null
+++ b/Documents/en/launchpad/launchpad-cli.md
@@ -0,0 +1,180 @@
+# Launchpad command line
+
+`vphone-launchpad-cli` drives the running Launchpad from Terminal or a script: install bundles, create, start and stop machines, and talk to the guest. Use it when you want Launchpad's behavior without clicking through the window.
+
+## Set it up
+
+The CLI ships in `vphone-launchpad.app/Contents/MacOS`. Link it onto your `PATH`:
+
+```sh
+ln -s /Applications/vphone-launchpad.app/Contents/MacOS/vphone-launchpad-cli /usr/local/bin/
+vphone-launchpad-cli help
+```
+
+It starts Launchpad when Launchpad is not running. A Launchpad the CLI starts opens hidden and does not take focus from the app in front; click its Dock icon, or Open Launchpad in the menu bar, to show the window. Pass `--foreground` (before the command, or among the options of any command but `exec`) to start it with its window in front instead. Neither changes a Launchpad that is already running.
+
+## Output and exit status
+
+- Progress lines go to stderr as they arrive.
+- The result is one JSON document on stdout.
+- The exit status is 0 on success and 1 on failure, with the reason on stderr.
+- Interrupting the CLI cancels a command that can be cancelled (`exec`, waits, CFW install). A bundle install or a machine creation belongs to the window and keeps running.
+
+Every command also appears in Launchpad's window and command history.
+
+## Commands
+
+Machine commands take `--root <library>` when two libraries hold a machine with the same name.
+
+### Status and bundles
+
+| Command | Does |
+| --- | --- |
+| `status` | Host checks, helper, default bundle, machine counts |
+| `bundle list` | Installed versions, receipts, cdhashes, check results, bound machines |
+| `bundle install-local <path> [--keep-default]` | Install a local `VPhone.bundle` folder or `.zip` |
+| `bundle install-release <version\|latest> [--keep-default]` | Download and install a GitHub release |
+| `bundle set-default <version>` | Make a version the default. `bundle use` is the old name |
+| `bundle verify <version>` | Re-check a version |
+| `bundle accept <version> [--off]` | Skip failed checks, or stop skipping them with `--off` |
+| `bundle remove <version>` | Remove a version no machine is bound to |
+
+To install a local build, move a machine to it, or compare two builds, see [Core Bundles and local builds](core-bundles.md).
+
+### Machines
+
+| Command | Does |
+| --- | --- |
+| `vm list` | Machines in every library with run state, Core Bundle and log path |
+| `vm start <name> [--headless] [--wait]` | Launch with the machine's bundle. `--wait` waits for vphoned |
+| `vm stop <name>` | Ask the guest to shut down (vphoned `system.shutdown`) and wait up to 30 s. When the guest cannot be asked or does not stop, end the virtual machine |
+| `vm wait <name>` | Wait for vphoned |
+| `vm log <name> [--lines <n>] [--kind create\|dfu\|patch]` | Read a console log |
+| `vm create <name> [options]` | The New Machine pipeline; see [Create a machine](#create-a-machine) |
+| `vm set-bundle <name> <version> [--update-environment]` | Bind a machine to another installed version |
+| `vm leases [--release]` | DHCP leases on the shared NAT network and the machine that owns each. `--release` frees the ones no machine in any library uses, through the helper (see [Addresses held by old MACs](../networking/addresses.md#addresses-held-by-old-macs)) |
+
+Notes:
+
+- In `vm list`, only a VM process holding the disk (`vphone-vm`, or Virtualization's VM service) makes a machine `running`. Any other process that has the disk open (`tail`, Spotlight, a backup tool) is listed in `diskOpenIn` (for example `12925 tail`) and leaves the machine `stopped`.
+- `vm start`, like `vphone-cli vm launch`, is not refused by a process that only has the disk open; it prints a note naming that process.
+- `vm start --wait` and `vm wait` also take `--timeout`.
+- `vm set-bundle --update-environment` also redeploys that version's guest environment and needs a stopped machine. A disk another process has open refuses it, naming that process, before the binding changes. If the update itself fails, the machine stays bound to the new version and `vm list` still shows the old `guestEnvironmentBundle`; run `cfw update-environment` to finish.
+
+### CFW
+
+These run through Launchpad's helper on a stopped machine, with the machine's own bundle. Each refuses a disk another process has open, naming it (`12925 tail`).
+
+| Command | Does |
+| --- | --- |
+| `cfw install <name>` | Install CFW. The helper puts temporary work files on the VM library's external volume when applicable |
+| `cfw update-environment <name>` | Redeploy the bundle's guest resources (vphoned, hook dylibs); nothing else changes |
+| `cfw update-kernel <name>` | Re-patch the kernelcache from the machine's current patch selection and swap it into Preboot, keeping the data. This is the data-preserving way to change a kernel patch on an installed VM; no restore tree is needed |
+
+### Guest
+
+`guest` commands and `--wait` go through the machine's `vphone.sock`, which every launch serves. Bundles up to 2.0.9 serve it only for machines launched with a window.
+
+| Command | Does |
+| --- | --- |
+| `guest send <name> <json>` | One raw `vphone.sock` request (tap, swipe, key, screenshot) |
+| `guest rpc <name> <method> [params]` | Any vphoned method; see [`Research/vphoned_http_api.md`](../../../Research/vphoned_http_api.md). When vphoned refuses it, the last stderr line is its error object as JSON (`code`, `message`, `results`, `reason` …) |
+| `guest push <name> <local> <guest-path> [--mode <octal>]` | Copy a Mac file into the guest. It streams through vphoned, so size is not limited by `guest rpc`'s 1 MiB JSON line; use it for binaries and IPAs. A guest path ending in `/` keeps the file's name; the mode defaults to the Mac file's permissions |
+| `guest pull <name> <guest-path> <local>` | Copy a guest file to the Mac, streamed. `local` may be a folder. The file replaces `local` only once complete |
+| `guest unlock <name> [--passcode <code>] [--timeout <seconds>]` | Turn the screen on and unlock the guest, whatever state it was in (vphoned `screen.unlock`). `--passcode` is needed only when the guest has one |
+
+### Run vphone-cli
+
+| Command | Does |
+| --- | --- |
+| `exec [--bundle <version>] <vphone-cli arguments>` | Run the default bundle's `vphone-cli`, or that version's, streaming its output. `--bundle` must come first |
+
+## Create a machine
+
+`vm create` runs the New Machine pipeline, bound to `--bundle <version>` or to the default bundle. The machine is cloned from a template, which is built first when missing (2.9), or restored on its own with `--no-template`.
+
+```sh
+vphone-launchpad-cli vm create rt-e --block system-debugserver-cfw-install
+```
+
+| Option | Does |
+| --- | --- |
+| `--bundle <version>` | Bind the machine to this installed version instead of the default |
+| `--device <product-type>` | Make another device; see [Other devices](#other-devices) |
+| `--preset <preset>` | A preset name, or the path of a preset plist (2.14), which the machine keeps a copy of |
+| `--block <patch>`, `--allow <patch>` | Turn one patch of the preset off or on; repeatable. See [Patch overrides](#patch-overrides) |
+| `--no-template` | Restore the machine on its own instead of cloning a template |
+| `--slim on\|off`, `--trim …`, `--keep-languages …`, `--service-profile …`, `--remove-apps …`, `--keep-apps …` | The slimming switches of `vphone-cli vm create`. Apple Account goes with the trimmed service profile, as in New Machine |
+| `--accounts-off` | Accepted, and changes nothing |
+| `--ipsw <path>` | Optional. Passed only to a 2.12.0 bundle, which stages the kernelcache mix with it, as New Machine's ipsw field does. A 2.12.1 bundle extracts natively |
+| `--kmutil-ssh <user@host>` | The Mac that links an iOS 18 guest's (`--device iPhone11,6`) kernel-first mix over ssh, as New Machine's macOS builder field. The password for ssh and sudo there comes from the client's `VPHONE_KMUTIL_SSH_PASSWORD`, never from an argument |
+| `--from <step>` | Retry from a step (`findTemplate` … `firstBoot`) with the options the creation started with |
+
+The parser also accepts `--iphone-source`, `--cloudos-source`, `--cpu`, `--memory`, `--disk-size`, `--network`, `--keep-artifacts` and `--no-wait`; see `vphone-launchpad-cli help`.
+
+The result names the template, whether this creation built it, and the patches it used.
+
+### Other devices
+
+| `--device` | Guest | Notes |
+| --- | --- | --- |
+| An iPad product type | iPadOS | See [iPadOS guests](../firmware/ipados.md) |
+| `AppleTV5,3` | Apple TV HD | Always restored on its own without slimming; takes the `tvos` preset unless `--preset` names another |
+| `AppleTV14,1` | Apple TV 4K (3rd generation) | The same, with the `tvos-4k` preset and its userland from the catalog's OTA |
+| `AppleTV18,1` | Apple TV 4K (4th generation) | Needs Launchpad and Core Bundle 2.13. Selects `tvos-4k`, restores independently without slimming, and takes tvOS 27.2 beta (`24K120`) from its full OTA over the Apple TV HD base. Creation requires macOS 27. A live boot is still pending; see the [bring-up notes](../../../Research/Firmware/tvos_support.md#apple-tv-4k-4th-generation) |
+
+Two more cases run steps as root through the helper:
+
+- `--preset minimal` (Minimal: a stock boot chain, kernel and TXM, with the system customized before the restore) is also restored on its own without slimming, and its `fw patch` runs as root through the helper. Its Userspace debugging box (`userspace-debugging` under Features in `vphone-cli fw patches`) is an `--allow` for each patch it lists.
+- For a machine whose cloudOS has no vphone600 components (its release's own cloudOS, a watch, an iOS 18 guest), the kernelcache mix is staged with `fw kernelcache` and linked by the helper as root.
+
+### Patch overrides
+
+`--block <patch>` and `--allow <patch>` take the identifiers that `vphone-cli fw patches` lists, once per patch:
+
+```sh
+vphone-launchpad-cli exec fw patches --preset <preset>
+```
+
+Launchpad reads that catalog from the creation's bundle, refuses an identifier no patch set declares or one both blocked and allowed, and keeps only what differs from the preset, as `fw set-patches` does. It then splits them the way New Machine does:
+
+- **Boot-chain patches** (AVPBooter, iBSS, iBEC, LLB, TXM, kernelcache, DeviceTree …) are part of the template's key. Find Template looks for a template built with them, and a template build records them with `fw set-patches` before `fw patch`.
+- **Guest patches** stay out of the template. The clone records them with `fw set-patches`, and the Apply Guest Patches step writes them with `cfw update-environment` through the helper before the first boot. A guest override alone therefore reuses the plain template.
+
+The result's `patches` object holds the preset, the `blocked` and `allowed` overrides, and the `guest` ones applied to the clone. With `--no-template` every override goes into the machine's own restore. `--from` refuses `--block` and `--allow`: a retry keeps the creation's patches.
+
+## Bundle fields in results
+
+| Command | Field | Meaning |
+| --- | --- | --- |
+| `status` | `defaultBundle` | The default version. `activeBundle` holds the same value for older scripts |
+| `bundle list` | `default` | This version is the default. `active` holds the same value for older scripts |
+| `bundle list` | `machines` | Names of the machines bound to this version |
+| `vm list` | `bundle` | The version the machine's host programs run with |
+| `vm list` | `guestEnvironmentBundle` | The version whose guest environment was installed last; `null` while unknown |
+| `vm list` | `bootChainBundle` | The version that built the boot chain; `null` for a machine created before Launchpad recorded it |
+| `vm create`, `cfw …`, `exec` | `bundle` | The version the command ran with |
+
+When `guestEnvironmentBundle` differs from `bundle`, host and guest come from different builds; `cfw update-environment` brings the guest in line.
+
+## Touch coordinates and display geometry
+
+Touch coordinates for `guest send` refer to the **full upright screenshot** that `t:screenshot` returns: after a quarter turn its width and height swap. The host converts that point into fixed-panel HID coordinates for both GUI and headless launches. A swipe keeps the geometry sampled at its start. If the geometry changes across a screenshot, you get an error rather than an image with ambiguous input coordinates.
+
+To diagnose rotated coordinate mismatches, read the geometry:
+
+```sh
+vphone-launchpad-cli guest send <name> '{"t":"display.geometry"}'
+```
+
+It returns the host's configured and captured pixel dimensions plus the live display-view bounds, rotation, aspect-fit drawing rect, and pointer/touch path, and changes no input or display state. `capture_pixels` is the raw host frame; `screenshot_pixels` and `input_orientation` describe input coordinates. Compare it with `device.screen`, `display.orientation` and the events the guest actually receives.
+
+## How it connects
+
+The CLI talks to the running Launchpad over a Unix socket at `~/Library/Application Support/vphone-launchpad/control.sock` (mode 0600, served only to the same user). It has no privileges and no state of its own: bundles are installed through Launchpad's helper, and each machine runs through the `vphone-cli` of its own Core Bundle. Nothing listens on the network; to use it from another machine, connect over ssh.
+
+## See also
+
+- [Core Bundles and local builds](core-bundles.md)
+- [Bundle integration](bundle-integration.md)
+- [Create and run](../machines/create-and-run.md)
diff --git a/Documents/en/machines/automation-api.md b/Documents/en/machines/automation-api.md
new file mode 100644
index 00000000..43812ae5
--- /dev/null
+++ b/Documents/en/machines/automation-api.md
@@ -0,0 +1,78 @@
+# Automation API
+
+Control a running VM from scripts over HTTP and WebSocket. Use this page to turn the API on, authenticate, and make your first calls; the [full API reference](../../../Research/vphoned_http_api.md) lists every route and method.
+
+## Turn it on
+
+Add `--api-listen` when you launch the VM:
+
+```sh
+vphone-cli vm launch myphone --api-listen 127.0.0.1:8765
+```
+
+After the VM starts, `vphone-vm` prints the address and a token:
+
+```text
+[api] HTTP/WebSocket API: http://127.0.0.1:8765
+[api] token: 3f9c…
+[api] send it as: Authorization: Bearer 3f9c…
+```
+
+- Without `--api-listen` there is no host listener.
+- Port `0` asks macOS for a free port; the actual address is printed after the VM starts.
+- `--api-listen` is unavailable with `--dfu`.
+
+> [!WARNING]
+> vphoned runs as root, and the API can read and write any guest file, list the keychain and load launch daemons. For local-only use, listen on `127.0.0.1` or `[::1]`. Any other address prints a warning: every machine that can reach it needs only the token, which travels in clear text over plain HTTP, so use it only on a trusted network.
+
+## The token
+
+The token is new for each launch: 32 random bytes, in hex. To use a fixed token, set `VPHONE_API_TOKEN` before launching; `vphone-cli vm launch` passes its environment through to `vphone-vm`. The value must be 16 to 256 characters of `A-Z a-z 0-9 - . _ ~`; any other non-empty value stops the launch.
+
+Send the token in any of these forms:
+
+| Form | Use for |
+| --- | --- |
+| `Authorization: Bearer <token>` header | HTTP, and WebSocket clients that can set headers |
+| `token=<token>` query item | WebSocket URLs, such as `ws://127.0.0.1:8765/v1/events?token=<token>` |
+| `Sec-WebSocket-Protocol: vphone-token.<token>` | WebSocket clients that can only set a subprotocol |
+
+A missing or wrong token gets `401 Unauthorized`, and the connection closes before anything reaches the guest.
+
+## Example calls
+
+```sh
+TOKEN=... # from the "[api] token:" line, or the VPHONE_API_TOKEN you set
+
+# Health check
+curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8765/v1/health
+
+# Call any method through /v1/rpc
+curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+ -d '{"method":"device.snapshot","params":{}}' http://127.0.0.1:8765/v1/rpc
+
+# Event stream
+websocat "ws://127.0.0.1:8765/v1/events?token=$TOKEN"
+
+# Interactive shell in the guest (websocat needs --binary)
+websocat --binary "ws://127.0.0.1:8765/v1/shell?token=$TOKEN&cols=120&rows=40"
+```
+
+Rules that trip up hand-written clients:
+
+- Every `POST` must send `Content-Type: application/json`, or it gets `415`.
+- A request with an `Origin` header, or with a `Host` other than `vphoned`, `localhost`, `127.0.0.1` or `::1`, gets `403`. This blocks browser pages from reaching the API.
+- `GET` routes only read. To change a setting, use `PUT` or `POST`, for example `PUT /v1/low-power-mode` with `{"enabled": true}`.
+
+Swift apps can use the `VPhoneAPIClient` in the `VPhoneAPIKit` package, which sends the token for you; see the reference for an example.
+
+## Without a network listener
+
+The VM's control socket accepts the same methods without the API listener: send `{"t":"rpc","method":"<method>","params":{}}` as one JSON line. See [Control socket](create-and-run.md#control-socket).
+
+## See also
+
+- [Full API reference](../../../Research/vphoned_http_api.md)
+- [Create and Run a VM](create-and-run.md)
+- [Port Forwarding](../networking/port-forwarding.md)
+- [Launchpad Command Line](../launchpad/launchpad-cli.md)
diff --git a/Documents/en/machines/boot-roms.md b/Documents/en/machines/boot-roms.md
new file mode 100644
index 00000000..a7980e97
--- /dev/null
+++ b/Documents/en/machines/boot-roms.md
@@ -0,0 +1,51 @@
+# Boot ROMs
+
+Choose which boot ROM and SEP boot ROM a VM starts from. Use this page to check which ROMs a VM uses or to switch between the open-source ROMs and Apple's.
+
+## Check and switch
+
+```sh
+vphone-cli vm info myphone # shows rom and seprom
+vphone-cli vm config myphone --rom openavb --seprom opensep # open-source ROMs
+vphone-cli vm config myphone --rom apple --seprom apple # Apple's ROMs
+```
+
+A switch applies from the VM's next start, without a restore, in either direction.
+
+| Option | Value | ROM |
+| --- | --- | --- |
+| `--rom` | `openavb` | The bundle's OpenAVB |
+| `--rom` | `apple` | Virtualization.framework's AVPBooter (the machine's own patched copy when it has one) |
+| `--rom` | a file path | Any other boot ROM |
+| `--seprom` | `opensep` | The bundle's OpenSEP |
+| `--seprom` | `apple` | Virtualization.framework's AVPSEPBooter |
+| `--seprom` | a file path | Any other SEP boot ROM |
+
+Both boot ROMs load the same patched LLB, and both SEP ROMs load the SEP firmware the restore installed, which is why no restore is needed.
+
+> [!NOTE]
+> Restoring a VM that boots OpenAVB needs `VPhone.bundle` 2.10.1 or newer.
+
+## Which ROMs a VM uses
+
+New VMs start from two open-source ROMs instead of the closed ones in Virtualization.framework:
+
+- [OpenAVB](https://github.com/owngoal-dev/OpenAVB) replaces AVPBooter, the boot ROM. It needs no patch, so `fw patch` leaves it alone.
+- [OpenSEP](https://github.com/owngoal-dev/OpenSEP) replaces AVPSEPBooter, the SEP boot ROM.
+
+With both, nothing Apple wrote runs before iBoot and SEPOS. VMs created by earlier versions keep Apple's ROMs until you switch them.
+
+## Where the ROMs come from
+
+Both ship in `VPhone.bundle`, prebuilt from pinned upstream commits. Each one's README says how to rebuild it and check it byte for byte:
+
+- [OpenAVB README](../../../VPhoneExecutable/VPhoneVirtualization/Resources/OpenAVB/README.md)
+- [OpenSEP README](../../../VPhoneExecutable/VPhoneVirtualization/Resources/OpenSEP/README.md)
+
+For the details, see the research notes on [OpenAVB](../../../Research/Firmware/openavb_boot_rom.md) and [OpenSEP](../../../Research/Firmware/opensep_sep_rom.md).
+
+## See also
+
+- [Create and Run a VM](create-and-run.md)
+- [Firmware Preparation](../firmware/firmware-preparation.md)
+- [Troubleshooting](../help/troubleshooting.md)
diff --git a/Documents/en/machines/create-and-run.md b/Documents/en/machines/create-and-run.md
new file mode 100644
index 00000000..9b0e33d6
--- /dev/null
+++ b/Documents/en/machines/create-and-run.md
@@ -0,0 +1,121 @@
+# Create and Run a VM
+
+Create, start and stop VMs with `vphone-cli` in Terminal. Use this page when you work without Launchpad, script VM creation, or need to repeat one stage of the process.
+
+Launchpad drives VMs through the `vphone-cli` inside `VPhone.bundle`; the same commands work in Terminal:
+
+```sh
+vphone-cli vm list
+vphone-cli vm launch myphone
+vphone-cli vm export myphone --out myphone.tzst
+```
+
+VMs are stored in `~/.vphone/`. Run `vphone-cli <group> --help` to see all commands.
+
+## Create a VM
+
+You need an iPhone17,3 restore IPSW and a compatible PCC/cloudOS IPSW, as local paths or URLs. [Compatibility](../firmware/compatibility.md) lists the pairs verified so far.
+
+```sh
+vphone-cli host preflight
+vphone-cli vm create myphone \
+ --iphone-source /path/to/iPhone17,3_Restore.ipsw \
+ --cloudos-source /path/to/cloudOS.ipsw
+```
+
+Creation runs these stages: prepare, firmware patch, online DFU restore, host-mounted CFW installation, first GUI boot.
+
+- It needs network access for the restore ticket.
+- CFW installation needs root. The bundle has no authorization dialog or privilege helper, so you provide root yourself.
+- The default virtual disk is 64 GB.
+
+Success ends with `[+] First boot: vphoned ping succeeded.` and `CFW VM created; vphoned connected. Guest user environment is untouched.` The VM is then stopped: the ping proves that vphoned answered during that boot, and no running VM is left behind.
+
+### Options
+
+| Option | Effect |
+| --- | --- |
+| `--iphone-version`, `--iphone-build` | Resolve the iPhone IPSW instead of passing `--iphone-source`, as `fw prepare` does, for `--device` (iPhone17,3 by default). |
+| `--cloudos-source` omitted | Use the cloudOS the catalog recommends for that release, as `fw catalog` lists it. |
+| `--disk-size` | Virtual disk size in GB (default 64). |
+| `--preset` | Patch preset name, or path to a preset plist (default `standard`). Run `fw patches` to see what each one applies. |
+| `--cpu` | CPU cores (default 8). |
+| `--memory` | Memory in MB (default 8192). |
+| `--network` | `nat` (default), `bridged`, `tunnel` or `none`. |
+| `--unlock-at-startup` | `on` or `off` (default). |
+| `--no-template` | Build the VM on its own instead of cloning it from a template. |
+| `--skip-first-boot` | Leave out the final boot, for a caller that boots the VM itself. |
+| `--bootstrap roothide` | Install a package environment during the first boot. See [Package Environment](package-environment.md). |
+| `--keep-artifacts` | Keep the large prepared restore tree. Leave it out when disk space matters. |
+
+`--cpu`, `--memory`, `--network` and `--unlock-at-startup` set the same `vm config` settings on the new VM.
+
+### Templates
+
+By default the pipeline builds a [template](../storage/templates.md) and clones the VM from it. The next `vm create` for the same device, iOS and cloudOS builds, preset and disk size clones from that template instead of restoring again. Pass `--no-template` to build the VM on its own.
+
+### Patches and firmware preparation
+
+The firmware workflow has one mode. It patches the boot chain and guest system, installs vphoned, and leaves the user environment empty: it does not install Sileo, apt, TrollStore, an SSH server or a VNC server. A patch preset selects which patches apply; `vphone-cli fw set-patches` with `--block` or `--allow` turns single patches off or on.
+
+Before patching, creation prepares the firmware: a temporary cloudOS restore supplies the GPU driver, and a cloudOS without vphone600 components needs a rebuilt kernelcache. See [Firmware Preparation](../firmware/firmware-preparation.md). To create several machines from one list, see [Many Machines](../storage/many-machines.md).
+
+## Start and stop
+
+```sh
+vphone-cli vm launch myphone # start the VM window and keep it running
+vphone-cli vm stop myphone # run from another terminal to stop it
+```
+
+`vm launch` starts the guest without waiting for vphoned; the daemon connects during boot. The VM window and menu provide Home and power keys, app installation and file browsing. `vm launch --headless` boots without a VM window or menu bar.
+
+These all shut the guest down cleanly (vphoned `system.shutdown`):
+
+- closing the VM window
+- ⌘Q
+- `vm stop`
+- Control-C in the `vm launch` terminal
+
+The VM ends once the guest has stopped, or after 15 seconds if it has not. A guest vphoned cannot answer for, such as one in DFU or still starting up, is turned off at once, as pulling the power would. A second Control-C turns it off without waiting.
+
+`vm stop` only signals the machine's own processes, `vphone-vm` and Virtualization's VM service. Another program that has the disk open, such as Launchpad measuring its size, Spotlight or a backup tool, is named and left running.
+
+## Control socket
+
+Each running VM has a control socket at `vphone.sock` in its folder (`~/.vphone/machines/<name>/vphone.sock`): one JSON line in, one JSON line out. Connections are served concurrently, and the socket also exists for a VM without a window, where `tap` and `swipe` go through vphoned's touch injection and screen images come from the guest.
+
+Besides `tap`, `swipe`, `key` and `screenshot`, an `rpc` request calls any vphoned method in the [API reference](../../../Research/vphoned_http_api.md):
+
+```sh
+printf '%s\n' '{"t":"rpc","method":"device.info","params":{}}' | nc -U ~/.vphone/machines/myphone/vphone.sock
+```
+
+For example, `input.key` with `{"name":"cmd+v"}` pastes, and `input.type` types text. This workflow installs no SSH or VNC endpoint. For HTTP and WebSocket access, see [Automation API](automation-api.md).
+
+## Run each stage by hand
+
+Use these when you investigate or repeat one phase. Keep a DFU boot running while `restore` talks to it:
+
+```sh
+vphone-cli vm new myphone
+vphone-cli fw prepare myphone \
+ --iphone-source /path/to/iPhone17,3_Restore.ipsw \
+ --cloudos-source /path/to/cloudOS.ipsw
+vphone-cli fw patch myphone
+
+vphone-cli vm launch myphone --dfu &
+vphone-cli restore myphone
+vphone-cli vm stop myphone
+
+vphone-cli cfw install myphone
+vphone-cli vm launch myphone
+```
+
+The online restore obtains its ticket in process. For an offline restore, see `vphone-cli restore --help` for `--get-shsh` and `--offline`. The manual flow does not run the first-boot ping check that `vm create` does.
+
+## See also
+
+- [Templates](../storage/templates.md)
+- [Device Name and Clock](device-name-and-clock.md)
+- [Library and Backups](../storage/library-and-backups.md)
+- [Sharing Disk Space](../storage/sharing-disk-space.md)
diff --git a/Documents/en/machines/device-name-and-clock.md b/Documents/en/machines/device-name-and-clock.md
new file mode 100644
index 00000000..b9f02d4b
--- /dev/null
+++ b/Documents/en/machines/device-name-and-clock.md
@@ -0,0 +1,42 @@
+# Device Name and Clock
+
+The guest takes its device name from the VM and its clock and time zone from your Mac. Read this page when a name or time in the guest is not what you expect.
+
+## Device name
+
+To change the name the guest shows, rename the VM:
+
+```sh
+vphone-cli vm rename myphone <new-name>
+```
+
+The guest shows the VM's name as its device name, in Xcode's device list and in `xcrun devicectl list devices`.
+
+- You cannot rename the device from inside the guest, or from Finder, Xcode or `idevicename`. A rename there reports success and changes nothing.
+- After `vm rename`, Finder and `ideviceinfo` show the new name as soon as the machine is up. Xcode and `devicectl` read the name when the device appears and may show the old name until the following boot.
+- A VM name of more than 255 UTF-8 bytes, or with a control character, is not used; the guest then shows its own name.
+
+`vphone-vm` hands the name to the guest each time it connects to vphoned, a few seconds into every boot, and the guest keeps it for the next boot. The guest's own name stays in its preferences, untouched.
+
+An existing machine moved to a bundle with this feature receives the guest library with its environment update and uses it from the boot after that.
+
+For the implementation, see [`Research/Guest/device_name_pinning.md`](../../../Research/Guest/device_name_pinning.md).
+
+## Clock and time zone
+
+The guest follows the Mac's time zone and clock. You do not need to set anything.
+
+`vphone-vm` sends the Mac's time zone each time it connects to vphoned, and the Mac's time then and every minute after. A guest that was off for a day, or sat under a sleeping Mac, is back on the Mac's time within a minute without reaching an NTP server. A guest within a second of the Mac is left alone.
+
+To give the guest a different date or time:
+
+1. In the guest, open **Settings > General > Date & Time**.
+2. Pick the date or time. This turns the guest's automatic time off, and the Mac's time is no longer applied.
+
+To go back to the Mac's time, turn **Set Automatically** on again there.
+
+## See also
+
+- [Create and Run a VM](create-and-run.md)
+- [Library and Backups](../storage/library-and-backups.md)
+- [Networking](../networking/overview.md)
diff --git a/Documents/en/machines/package-environment.md b/Documents/en/machines/package-environment.md
new file mode 100644
index 00000000..b166c626
--- /dev/null
+++ b/Documents/en/machines/package-environment.md
@@ -0,0 +1,50 @@
+# Package Environment
+
+Install a package manager in the VM, or remove it. A new VM has no package manager; follow this page when you need `apt`, a shell, SSH or other command-line tools in the guest.
+
+## Install
+
+1. In the VM window's menu bar, choose **Apps > Install Bootstrap…** and select the **roothide** layout (**rootless** is deprecated). This installs Irisin in the VM.
+2. In Irisin, open the **OwnGoal Packages** repository, find **OwnGoal Bootstrap for vphone** (`owngoal-bootstrap-vphone`), and install it with **Bootstrap Install**.
+3. After this first installation, install further packages normally.
+
+`owngoal-bootstrap-vphone` brings in everything a VM needs in a single pass: `apt` and `dpkg`, `bash`, `zsh` and `dash`, `sudo`, the core command-line tools, `openssh-server`, `curl`, `wget`, `vim`, `git`, `uikittools`, `launchctl`, and the OwnGoal apps.
+
+> [!WARNING]
+> Do not install these packages one by one. Several depend on one another, and `openssh-server` declares some dependencies circularly, so separate installs can fail partway.
+
+If the first installation fails, do not repair it in place. Choose **Apps > Uninstall Bootstrap…**, then start again from step 1.
+
+### Install while creating the VM
+
+```sh
+vphone-cli vm create myphone --bootstrap roothide ...
+```
+
+`--bootstrap roothide` does steps 1 and 2 during the new machine's first boot: it installs Irisin, then `owngoal-bootstrap-vphone` with Bootstrap Install through `irisin-cli`, from the repositories Irisin recommends. Step 2 needs an Irisin whose `irisin-cli install` has `--repository` and `--bootstrap-install`.
+
+## Remove
+
+Choose **Apps > Uninstall Bootstrap…**. The VM restarts after removal.
+
+Irisin keeps its data (downloads, journal, settings) in `Documents/wiki.qaq.irisin` under its home:
+
+| Layout | Irisin's home | After uninstalling |
+| --- | --- | --- |
+| roothide | The environment's own `/var/mobile` | The data is removed with everything else. |
+| rootless | The system's `/var/mobile` | The data stays. |
+
+## More options
+
+Hold Option while opening the **Apps** menu to see two more items:
+
+- **Install Bootstrap from File…:** Installs from a local Irisin `.deb`.
+- **Uninstall Bootstrap Without Restarting…:** Removes the environment without restarting the VM.
+
+The same operations are available through the automation API (`bootstrap.install`, `bootstrap.status`). See the [API reference](../../../Research/vphoned_http_api.md).
+
+## See also
+
+- [Create and Run a VM](create-and-run.md)
+- [Automation API](automation-api.md)
+- [Troubleshooting](../help/troubleshooting.md)
diff --git a/Documents/en/networking/addresses.md b/Documents/en/networking/addresses.md
new file mode 100644
index 00000000..1fd92eeb
--- /dev/null
+++ b/Documents/en/networking/addresses.md
@@ -0,0 +1,80 @@
+# MAC and IP addresses
+
+This page covers the guest's saved MAC address, freeing DHCP leases that old MACs still hold, and giving a guest a fixed IPv4 address.
+
+## MAC address
+
+The first launch gives the guest's network card a random, locally administered MAC address and saves it in `config.plist`, the way it saves the machine identifier. The guest then keeps one identity, and one DHCP lease, across launches.
+
+To set or replace it:
+
+```sh
+vphone-cli vm config <name> --mac 02:11:22:33:44:55
+vphone-cli vm config <name> --mac random # a new one now
+vphone-cli vm config <name> --mac auto # a new one at the next launch
+```
+
+A cloned machine keeps the MAC of the original, like its machine identifier. Before running both at once, either clone with `vm clone --new-identity`, which gives the copy a new identity and MAC, or give the copy a new MAC. `--new-identity` also clears the copy's fixed address, port forwards and mDNS name.
+
+## Addresses held by old MACs
+
+Symptom: in `nat` mode, new guests get higher and higher addresses, until they reach the fixed addresses you picked high in the range.
+
+List the leases on the shared network and who owns each, then release the orphans (needs `VPhone.bundle` 2.5 or later):
+
+```sh
+vphone-cli vm leases
+sudo vphone-cli vm leases --release-orphans
+```
+
+Through Launchpad:
+
+```sh
+vphone-launchpad-cli vm leases
+vphone-launchpad-cli vm leases --release
+```
+
+In the Launchpad window, Host Setup shows the count under NAT Network, and Release… frees them after an administrator approves. Launchpad compares against every library it lists.
+
+An orphan is an iOS or iPadOS guest's lease whose MAC belongs to no machine in the library and whose lease has run out. `--release-orphans` removes the orphans from `/var/db/dhcpd_leases` and has the DHCP server read the file again, so it needs root. It never touches:
+
+- a machine's own lease, even one that ran out while the machine was stopped;
+- a lease that has not run out, such as a running guest's whose MAC was just replaced;
+- leases of other VM apps, or of devices on Internet Sharing.
+
+Machines in another library count only when that library is named too: repeat `--library-root` for each. The release refuses to run when a library has no machines or a machine's settings cannot be read, since every lease there would look orphaned.
+
+Why it happens: the Mac's DHCP server keeps each address bound to the MAC it was given to, even after the lease runs out, and hands it to anyone else only once every other address in the range is taken. Deleting a machine or replacing its MAC leaves its address bound to a MAC nothing uses any more, and so does every launch made before MACs were saved.
+
+## Fixed address
+
+`--ip` gives the guest a fixed IPv4 address. Without a prefix, `/24` is assumed. `--gateway` and `--dns` are optional; `auto` returns them to the default. `--ip dhcp` removes the fixed address.
+
+```sh
+vphone-cli vm config <name> --ip 192.168.65.50
+vphone-cli vm config <name> --network tunnel --ip 10.20.0.5/16 --dns 1.1.1.1
+vphone-cli vm config <name> --ip dhcp
+```
+
+How the address reaches the guest depends on the mode:
+
+| Mode | Address | How it is applied |
+| --- | --- | --- |
+| `nat` | On the Mac's shared NAT network: normally `192.168.65.0/24`, or `192.168.64.0/24` for a machine with `--nat-peers off` (see [Machines reaching each other](peers.md)) | vphoned writes it into the guest's network settings. The gateway and DNS are the Mac, `192.168.65.1` or `192.168.64.1`. |
+| `tunnel` | Any private subnet | The tunnel's own DHCP hands it out. The gateway, which is also the DNS resolver, is the subnet's first address unless `--gateway` names another. |
+| `bridged` | An address on the physical network | vphoned writes it into the guest. Set `--gateway` and `--dns` to the network's own. |
+
+> [!TIP]
+> An address on the shared `nat` network is not reserved in the Mac's DHCP server. Pick one high in the range, such as `.200`, that DHCP is unlikely to have handed to another VM.
+
+In `nat` mode the address has to be on the shared network the machine joins: the second one (`192.168.65.0/24`) for machines that reach each other, which is the default, or the first (`192.168.64.0/24`) with `--nat-peers off`. Both follow vmnet's `Shared_Net_Address` if it has been moved. For any other subnet, use `tunnel`.
+
+vphoned applies the address each time `vphone-vm` connects to it, so a guest changed while the Mac was not looking is put back. It only undoes its own setting: an address typed into the guest's Settings app is left alone when the VM goes back to DHCP.
+
+macOS 26 can give a VM a NAT network of its own, but the subnet then stays reserved after the VM stops (still reserved 40 minutes later in testing), and every launch on it fails meanwhile, so vphone does not use it.
+
+## See also
+
+- [Networking](overview.md)
+- [Port forwarding](port-forwarding.md)
+- [Machines reaching each other](peers.md)
diff --git a/Documents/en/networking/names.md b/Documents/en/networking/names.md
new file mode 100644
index 00000000..f1a5f921
--- /dev/null
+++ b/Documents/en/networking/names.md
@@ -0,0 +1,70 @@
+# Names on the network
+
+This page covers two names: the guest's own `.local` name, which lets the Mac reach it by name, and this Mac's `.local` name as the guest resolves it.
+
+## The guest's name (mDNS)
+
+Off by default. Turn it on and reach the guest by name:
+
+```sh
+vphone-cli vm config <name> --mdns on
+ping <vm-name>.local
+```
+
+| Setting | Effect |
+| --- | --- |
+| `--mdns on` | The guest answers to `<vm-name>.local`. Anything but letters and digits in the VM name becomes a hyphen: `ipad_pro.13` becomes `ipad-pro-13.local`. |
+| `--mdns <name>` | The guest answers to another name you pick. |
+| `--mdns off` | The guest's own name comes back. |
+
+The name works in every mode, `none` included:
+
+| Mode | `<name>.local` resolves to |
+| --- | --- |
+| `nat` | The guest's address on the shared network, and its USB link address |
+| `bridged` | The guest's LAN address, for every device on the LAN, and its USB link address on the Mac |
+| `tunnel`, `none` | The guest's USB link address, on the Mac only |
+
+Besides its network card, a guest has the network link that a USB-connected iPhone gives the Mac. It shows up on the Mac as an `en` interface with a `169.254` address. That address is link-local, but the Mac reaches the guest on it directly, so in `tunnel` mode a connection to `<name>.local` reaches a guest service without a port forward.
+
+Things to know:
+
+- If another device already uses the name, mDNS renames the guest (`name-2`).
+- `vm rename` renames a name that `--mdns on` derived from the VM name; a name you picked by hand stays.
+- A VM stopped with `vm stop` or by closing its window cannot withdraw its announcement. The Mac's resolver keeps returning the old address until the cached record expires, which for a host address is 75 minutes (TTL 4500 s).
+
+vphoned sets the name in the guest's network settings (`LocalHostName`) each time `vphone-vm` connects, and the guest's mDNSResponder announces it on every link it has.
+
+## This Mac's name in the guest
+
+On by default. The guest resolves this Mac's mDNS name (`scutil --get LocalHostName`, plus `.local`) at once, to the address it reaches the Mac at:
+
+| Mode | `<Mac>.local` in the guest |
+| --- | --- |
+| `nat` | The Mac on the shared network, usually `192.168.65.1` (`192.168.64.1` with `--nat-peers off`) |
+| `tunnel` | The gateway, `192.168.127.1` by default. Connections to it reach the Mac's loopback (`127.0.0.1`), the way `10.0.2.2` does in QEMU and VirtualBox |
+| `bridged` | The Mac's address on the bridged interface |
+
+To withdraw it:
+
+```sh
+vphone-cli vm config <name> --mac-name off
+```
+
+To see what the guest's resolver returns, and whether each address connects:
+
+```sh
+vphone-launchpad-cli guest rpc <name> network.resolve '{"host":"<Mac>.local","family":"ipv4","port":8000}'
+```
+
+### Why it is needed
+
+Over mDNS alone, an IPv4 lookup of the Mac's name in the guest could fail. The guest also hears the Mac on the USB link, where the Mac has no IPv4 address and answers "no such record". Whichever link answered first decided the lookup, so an app that wanted an IPv4 address got an error until a real answer had been cached from another link. A lookup also listed the Mac's `169.254` address on the USB link first; iOS routes `169.254.0.0/16` through its primary interface, so a plain socket connecting to that address could leave through `en0`, where nothing answers, and wait out its timeout.
+
+vphoned registers the name with the guest's own mDNSResponder as a local record, the way an `/etc/hosts` line works: it answers an IPv4 lookup at once with that one address, without asking the network and without the answers it has cached. It does so each time `vphone-vm` connects, and again when vphoned starts, so the name is in place before apps run after a reboot. The guest's system volume is read-only, so `/etc/hosts` itself is not edited, and nothing is announced on any network. IPv6 lookups still go to mDNS.
+
+## See also
+
+- [Networking](overview.md)
+- [MAC and IP addresses](addresses.md)
+- [Tunnel mode](tunnel.md)
diff --git a/Documents/en/networking/overview.md b/Documents/en/networking/overview.md
new file mode 100644
index 00000000..e9304ffc
--- /dev/null
+++ b/Documents/en/networking/overview.md
@@ -0,0 +1,56 @@
+# Networking
+
+Each VM has one network mode. This page shows how to pick it and how to unplug a running VM's network; the other pages in this section cover tunnel mode, addresses, port forwarding, names and machines reaching each other.
+
+## Network modes
+
+| Mode | How the guest reaches the internet | Use it when |
+| --- | --- | --- |
+| `nat` | Virtualization.framework's built-in NAT | The default. The Mac has no VPN, or the VPN does not need to carry the guest. |
+| `bridged` | Directly on a physical interface of the Mac, with its own address on that network | The guest has to be reachable from other machines on the LAN. |
+| [`tunnel`](tunnel.md) | Through ordinary connections that `vphone-vm` opens on the Mac | The Mac's traffic goes through a VPN or a proxy app, and the guest's traffic must follow it. |
+| `none` | No network device | The guest must stay offline. |
+
+The mode is stored in the VM's `config.plist` and read when the VM starts, so a change applies from the next launch.
+
+## Choose a mode
+
+In Launchpad:
+
+1. Stop the machine.
+2. Choose Settings… from the `⋯` menu or the right-click menu.
+3. Pick the mode in the Network section.
+
+New Machine sets the mode under Advanced Options. With one machine selected, Settings… also has Address and Port Forwarding sections.
+
+From the command line:
+
+```sh
+vphone-cli vm config <name> --network tunnel
+# or through Launchpad
+vphone-launchpad-cli exec vm config <name> --network tunnel
+```
+
+`tunnel` needs a `VPhone.bundle` that lists it in `vphone-cli vm config --help`. An older bundle rejects the setting.
+
+## Unplug a running VM
+
+`vm network` acts on a running VM, and nothing it does is saved:
+
+```sh
+vphone-cli vm network <name> # state of the NIC
+vphone-cli vm network <name> --link down # unplug the cable
+vphone-cli vm network <name> --link up # plug it back in
+```
+
+The guest sees the link drop and come back. The same request is available on `vphone.sock` as `{"t":"network"}`, with `"link":"down"` or `"link":"up"`.
+
+> [!NOTE]
+> A running VM cannot move to another network. Virtualization accepts the change and then stops the VM with an internal error, so `vm network` only ever puts back the network the VM started on. To change the mode, use `vm config` and restart the VM.
+
+## See also
+
+- [Tunnel mode](tunnel.md): a Mac behind a VPN or proxy app
+- [MAC and IP addresses](addresses.md): the saved MAC, leases held by old MACs, fixed addresses
+- [Port forwarding](port-forwarding.md): carry a port on the Mac into the guest
+- [Names on the network](names.md) and [Machines reaching each other](peers.md)
diff --git a/Documents/en/networking/peers.md b/Documents/en/networking/peers.md
new file mode 100644
index 00000000..bdf867cc
--- /dev/null
+++ b/Documents/en/networking/peers.md
@@ -0,0 +1,33 @@
+# Machines reaching each other
+
+`nat` machines on one Mac reach each other directly, Bonjour included. A virtual Apple Watch pairs with a virtual iPhone this way. This page shows how to keep one machine apart.
+
+## Isolate a machine
+
+```sh
+vphone-cli vm config <name> --nat-peers off # isolate this guest again
+vphone-cli vm config <name> --nat-peers on # the default
+```
+
+In Launchpad it is "Reach other NAT machines" in the machine's Network settings. The change applies from the next launch.
+
+An isolated guest reaches the Mac and the internet, but not another VM. Isolation is a setting of each machine's own attachment, so a machine that opts out stays isolated whatever the others do.
+
+## Which network a machine is on
+
+| Setting | Shared network | The Mac's address |
+| --- | --- | --- |
+| `--nat-peers on` (default) | `192.168.65.0/24` | `192.168.65.1` |
+| `--nat-peers off` | `192.168.64.0/24` | `192.168.64.1` |
+
+A [fixed address](addresses.md#fixed-address) (`--ip`) must be on the network the machine joins. A machine whose fixed address is on the first network (`192.168.64.0/24`) stays isolated unless it asks for its peers, and then needs an address on the second one.
+
+## Background
+
+By default Virtualization.framework isolates each `nat` guest from the others on the Mac's shared network. vphone turns that isolation off, and vmnet then puts the machines that reach each other on a second shared network, the block after the first. The switch is private to Virtualization.framework; a version without it leaves every guest isolated and says so when the VM starts.
+
+## See also
+
+- [Networking](overview.md)
+- [MAC and IP addresses](addresses.md)
+- [Names on the network](names.md)
diff --git a/Documents/en/networking/port-forwarding.md b/Documents/en/networking/port-forwarding.md
new file mode 100644
index 00000000..ba791a11
--- /dev/null
+++ b/Documents/en/networking/port-forwarding.md
@@ -0,0 +1,40 @@
+# Port forwarding
+
+Use `--forward` to carry a port on the Mac into the guest in `nat` and `tunnel` modes. `bridged` puts the guest on the LAN with its own address, so it needs no forwards.
+
+## Add and remove forwards
+
+```sh
+vphone-cli vm config <name> --forward tcp:8022:22
+vphone-cli vm config <name> --forward udp:0.0.0.0:5353:53
+vphone-cli vm config <name> --remove-forward 8022
+vphone-cli vm config <name> --clear-forwards
+```
+
+The form is:
+
+```text
+[tcp|udp:][host-address:]host-port:guest-port
+```
+
+| Part | Meaning |
+| --- | --- |
+| `tcp` or `udp` | Protocol |
+| `host-address` | Where the forward listens on the Mac. The default is `127.0.0.1`; `0.0.0.0` makes it reachable from other devices on the LAN. |
+| `host-port` | Port on the Mac |
+| `guest-port` | Port in the guest |
+
+Repeat `--forward` for more ports. In Launchpad, the machine's Settings… has a Port Forwarding section.
+
+## How forwards behave
+
+- `vphone-vm` opens the listeners when the VM starts and closes them when it stops.
+- In `nat` mode it connects to the guest's address: the [fixed one](addresses.md#fixed-address), or the one vphoned reports.
+- In `tunnel` mode the connection reaches the guest as if it came from the gateway.
+- A port that is already taken on the Mac is reported in the VM's log and skipped; the other forwards still work.
+
+## See also
+
+- [Networking](overview.md)
+- [Tunnel mode](tunnel.md)
+- [MAC and IP addresses](addresses.md)
diff --git a/Documents/en/networking/tunnel.md b/Documents/en/networking/tunnel.md
new file mode 100644
index 00000000..fe8ca879
--- /dev/null
+++ b/Documents/en/networking/tunnel.md
@@ -0,0 +1,66 @@
+# Tunnel mode
+
+Use `tunnel` mode when the Mac's traffic goes through a VPN or a proxy app and the guest's traffic must go the same way. In `nat` and `bridged`, the guest's packets bypass the VPN.
+
+## Turn it on
+
+Stop the machine, then:
+
+```sh
+vphone-cli vm config <name> --network tunnel
+```
+
+In Launchpad, pick `tunnel` in the Network section of the machine's Settings…. The bundle must list `tunnel` in `vphone-cli vm config --help`; an older bundle rejects it.
+
+## Check that it works
+
+1. Start the machine and wait for it to finish booting.
+2. Read the guest's address:
+
+ ```sh
+ vphone-launchpad-cli guest rpc <name> device.network
+ ```
+
+ `en0` should show `192.168.127.3`. If it shows only an `fe80::` address, DHCP has not finished yet. Wait a few seconds and try again.
+3. Open a page in the guest:
+
+ ```sh
+ vphone-launchpad-cli guest rpc <name> apps.open_url '{"url":"https://example.com"}'
+ ```
+
+4. On the Mac, check that the connections belong to `vphone-vm` and use the VPN's address:
+
+ ```sh
+ lsof -nP -a -i -p "$(pgrep -f 'vphone-vm.*<name>')"
+ ```
+
+## What the guest sees
+
+| Item | Value |
+| --- | --- |
+| Guest address | `192.168.127.3/24` by DHCP, or the [fixed address](addresses.md#fixed-address) |
+| Gateway and DNS | `192.168.127.1`, or the first address of the fixed address's subnet |
+| MTU | 1500 |
+| DNS | Queries to `192.168.127.1` go to the Mac's resolver |
+| Other connections to the gateway | The Mac's loopback, `127.0.0.1` (TCP and UDP) |
+
+In a proxy app the guest shows up as its own client, named after the machine, and the app's rules apply to it as to any other app.
+
+## Limits
+
+- **IPv4 only.** The guest gets no IPv6 address, and IPv6 traffic is dropped.
+- **Outbound only, apart from forwarded ports.** Nothing on the Mac or the LAN can reach the guest through this network except the ports listed under [Port forwarding](port-forwarding.md). USB access (`iproxy`, `ideviceinstaller`) and `vphone.sock` do not use the guest network, so they still work. A `.local` name also reaches the guest over its USB link; see [Names on the network](names.md).
+- **Ping reaches the gateway only.** ICMP to the internet is not forwarded, so `ping 1.1.1.1` in the guest fails even while TCP and UDP work.
+- **Throughput is limited by `vphone-vm`.** Every packet is handled in that process. Downloads and video work, but `nat` is faster when no VPN is involved.
+
+## How it works
+
+When a VPN owns the Mac's default route (WireGuard, Cloudflare WARP, or a proxy app in TUN mode such as Surge or Clash), packets that `nat` and `bridged` send out through a physical interface skip the VPN. They leave unencrypted, or not at all.
+
+In `tunnel` mode the guest's network card is implemented inside `vphone-vm`. It answers DHCP, ARP and ping for the gateway, and turns each guest TCP connection and UDP flow into a normal socket on the Mac. Those sockets follow the Mac's routing table like any other app's, so the VPN carries them. It needs no root, no new network interface and no change to the Mac's network settings.
+
+## See also
+
+- [Networking](overview.md)
+- [MAC and IP addresses](addresses.md)
+- [Port forwarding](port-forwarding.md)
diff --git a/Documents/en/storage/library-and-backups.md b/Documents/en/storage/library-and-backups.md
new file mode 100644
index 00000000..586bc505
--- /dev/null
+++ b/Documents/en/storage/library-and-backups.md
@@ -0,0 +1,69 @@
+# Library, firmware and backups
+
+Where vphone keeps machines and downloaded firmware, how to move them, and how to copy, back up and restore a machine. Read it when you plan disk space, relocate the library, or need a second copy of a machine.
+
+## Back up, copy and restore
+
+```sh
+vphone-cli vm list
+vphone-cli vm info myphone
+vphone-cli vm clone myphone copy # backup: same identity
+vphone-cli vm clone myphone second --new-identity # a second device
+vphone-cli vm export myphone --out myphone.tzst
+vphone-cli vm import myphone.tzst --name restored
+```
+
+`vm clone` copies a stopped machine, using APFS copy-on-write when available. It refuses while the source runs.
+
+| Clone | Identity | Use |
+| --- | --- | --- |
+| Plain `vm clone` | Same machine identifier and MAC address | A backup. It cannot run beside the original. |
+| `vm clone --new-identity` | New machine identifier (ECID), and with it a new UDID; new MAC address on its first start | A second device that runs beside the original |
+
+A `--new-identity` copy:
+
+- clears its fixed IPv4 address, port forwards and a hand-chosen mDNS name, since they would collide with the original's. An mDNS name that `--mdns on` derived from the original's name follows the new name, as on rename. Set new ones with `vm config` if you need them.
+- keeps the original's data, apps and settings; no restore is needed.
+- needs you to unlock it and trust this Mac again before lockdown tools such as `ideviceinstaller` work.
+- shares its disk blocks with the original on APFS and holds only what it changes, about 0.35 GB after its first boots, although `du` and Finder report the full size for each.
+
+> [!WARNING]
+> Do not swap `SEPStorage`, `nvram.bin` or the disk image between machines. One restore made them together, and a guest whose SEP storage does not match its disk panics at boot.
+
+## Where files live
+
+| Default path | Contents |
+| --- | --- |
+| `~/.vphone/machines/<name>/` | One VM, including its disk, `config.plist`, and patch work files |
+| `~/.vphone/ipsws/` | Remote source IPSWs, shared by every VM; local IPSWs are read in place |
+| `~/.vphone/gpu-drivers/<version>_<build>/` | GPU driver bundles extracted from cloudOS, shared by every VM |
+| `~/.vphone/kernelcache/` | Kernelcache mixes for cloudOS releases without vphone600 components, their staged volumes and the donor extraction |
+
+To move them:
+
+| Setting | Moves |
+| --- | --- |
+| `VPHONE_ROOT` | The whole `~/.vphone` data root: the machine library and the caches |
+| `VPHONE_LIBRARY_ROOT` | The machine library alone; takes precedence over `VPHONE_ROOT` |
+| `--ipsw-cache <dir>` on `vm create` and `fw prepare` | The IPSW cache alone |
+
+## IPSW cache and downloads
+
+Downloaded IPSWs stay cached until you delete them, so a second machine from the same URL downloads nothing. In Launchpad, delete them with **File > Downloaded IPSWs…**.
+
+The prepared restore tree is removed after a successful `vm create` unless you pass `--keep-artifacts`. Machines prepared by an earlier build may still hold a `.ipsw-cache/` directory; it is safe to delete, and `vm export` leaves it out.
+
+A remote IPSW downloads over four connections at once when its server answers HTTP range requests, as Apple's CDN does. Each connection fetches 32 MB segments in turn and resumes a dropped segment where it stopped. `--download-connections <n>` on `fw prepare` sets the count, from 1 to 16. With 1 the IPSW downloads as a single stream, which is also what a server that ignores ranges gets.
+
+## Disk space and memory
+
+Run resource-heavy creations one at a time. The IPSWs and the temporary restore tree take substantial disk space, and patching large caches can use a lot of memory. Check free space before you start a second machine.
+
+Launchpad places CFW scratch files on the library's mounted external volume when that applies. Standalone `vphone-cli cfw install` defaults to `/private/var/tmp` and accepts `--work-parent` for a root-owned private directory.
+
+## See also
+
+- [Snapshots](snapshots.md)
+- [Templates](templates.md)
+- [Sharing disk space between VMs](sharing-disk-space.md)
+- [Create and run a machine](../machines/create-and-run.md)
diff --git a/Documents/en/storage/many-machines.md b/Documents/en/storage/many-machines.md
new file mode 100644
index 00000000..07929a5b
--- /dev/null
+++ b/Documents/en/storage/many-machines.md
@@ -0,0 +1,61 @@
+# Create many machines
+
+`vm create-bulk` creates every machine a plist describes, in order. Use it to set up a lab or CI fleet from one file.
+
+## Run it
+
+```sh
+vphone-cli vm create-bulk list.plist --dry-run # print each machine's vm create command
+vphone-cli vm create-bulk list.plist
+```
+
+Run it with `sudo` when a machine needs a build, as with `vm create`.
+
+## Write the list
+
+```xml
+<dict>
+ <key>version</key> <integer>1</integer>
+ <key>defaults</key>
+ <dict>
+ <key>library-root</key> <string>~/vphone-lab</string>
+ <key>iphone-version</key> <string>26.1</string>
+ <key>preset</key> <string>presets/lab.plist</string>
+ <key>cpu</key> <integer>4</integer>
+ </dict>
+ <key>machines</key>
+ <array>
+ <dict><key>name</key> <string>ci-1</string></dict>
+ <dict><key>name</key> <string>ci-2</string></dict>
+ <dict>
+ <key>name</key> <string>fuzz</string>
+ <key>iphone-build</key> <string>23F77</string>
+ <key>iphone-version</key> <false/>
+ <key>no-template</key> <true/>
+ </dict>
+ </array>
+</dict>
+```
+
+- Each key is a `vm create` option's long name, with its value: a string or integer, `true` for a flag, an array for `keep-apps`.
+- `defaults` apply to every machine. A machine's own keys win, and `false` clears a default.
+- Relative paths resolve against the plist's folder.
+- `library-root` puts the machines in another library; `-l` on the command line overrides it.
+- Every machine must name its firmware (`iphone-version`, `iphone-build`, or `iphone-source` with `cloudos-source`) or a `template`, so nothing prompts.
+
+## How the run behaves
+
+All machines are checked as `vm create` checks them before the first is made. Machines are created in order, so those with one template key clone the template the first one built. The first failure stops the run.
+
+A name that already exists is an error. Two flags change that; they cannot be combined:
+
+| Flag | Effect |
+| --- | --- |
+| `--skip-existing` | Skips a machine whose name exists, so a run that stopped can be run again for the rest. A machine that failed is left as it stopped, so delete it first or it is skipped too. |
+| `--force-override` | Deletes that VM just before its machine is created. Refuses one that is running, or a folder that is not a VM. |
+
+## See also
+
+- [Templates](templates.md)
+- [Building and finding templates](template-building.md)
+- [Create and run a machine](../machines/create-and-run.md)
diff --git a/Documents/en/storage/shader-cache.md b/Documents/en/storage/shader-cache.md
new file mode 100644
index 00000000..bfdeec89
--- /dev/null
+++ b/Documents/en/storage/shader-cache.md
@@ -0,0 +1,64 @@
+# Persistent shader caches
+
+Machines keep their compiled GPU shaders between boots, so animations lag only while shaders compile on the first runs. Read this page to turn the cache on for an existing machine or to reset it.
+
+New machines created with the Standard preset enable the Task3 kernel patch and guest Metal cache reuse automatically. The host saves its cache in `<machine>/ShaderCache`, for example `~/.vphone/machines/Lychee/ShaderCache`. A changed executable gets a new host cache identity.
+
+## Turn it on for an existing machine
+
+Install a Core Bundle that contains this feature, and bind the stopped machine to it. Then update the guest environment and the kernel. Both updates keep the guest's data; no restore or `fw patch` is needed.
+
+### In Launchpad
+
+1. Choose **Update Guest Environment** from the machine's actions menu.
+2. Choose **Update Kernel** in its **Patches** inspector.
+
+Standard now selects **GPU Task3 shader cache** automatically. An explicit per-machine opt-out is preserved; if the patch was unchecked, enable it in the editor first.
+
+### With the Launchpad CLI
+
+```sh
+# Replace <version> with the installed Core Bundle version from bundle list.
+vphone-launchpad-cli vm stop Lychee
+vphone-launchpad-cli vm set-bundle Lychee <version> --update-environment
+vphone-launchpad-cli cfw update-kernel Lychee
+vphone-launchpad-cli vm start Lychee --wait
+```
+
+- `--update-environment` redeploys the guest libraries and the cache-reuse marker.
+- `cfw update-kernel` re-patches the pristine kernel in `FirmwareOriginals` with the current selection and replaces the kernelcache in Preboot.
+
+Changing the Core Bundle binding alone does not update the installed kernel.
+
+### With vphone-cli alone
+
+With the machine off, run the new bundle's commands with root authorization:
+
+```sh
+sudo vphone-cli cfw update-environment Lychee
+sudo vphone-cli cfw update-kernel Lychee
+```
+
+`vphone-cli fw patches Lychee` shows pending patches. Both update commands apply the machine's current selection, including any other pending guest or kernel changes.
+
+### Older machines without a pristine kernel
+
+A machine with no pristine kernel in `FirmwareOriginals` needs `fw prepare` and `fw patch` with the new bundle first, so the fallback restore tree contains the updated kernel. Then run `cfw update-kernel`. Do not run `restore`.
+
+## Reset the host cache
+
+Stop the machine, then delete its `ShaderCache` directory. The next launch starts a fresh host cache.
+
+Guest Metal caches are separate files inside `Disk.img`, so clearing the host cache does not necessarily reproduce all first-run lag.
+
+## Limits
+
+- Task3 applies to cloudOS 26.4 kernels only and is disabled in the tvOS presets.
+- On a host older than macOS 27, the guest negotiates the host's own maximum version and keeps that version's features, so the host cache stays per-boot there.
+- Runtime validation covered macOS 27.0.1, cloudOS 26.4, and iOS 27.0.1 and 26.6.2 guests. Older hosts were checked from their framework code, not run.
+
+## See also
+
+- [Core Bundles](../launchpad/core-bundles.md)
+- [Launchpad CLI](../launchpad/launchpad-cli.md)
+- [Library, firmware and backups](library-and-backups.md)
diff --git a/Documents/en/storage/sharing-disk-space.md b/Documents/en/storage/sharing-disk-space.md
new file mode 100644
index 00000000..e7dcf654
--- /dev/null
+++ b/Documents/en/storage/sharing-disk-space.md
@@ -0,0 +1,50 @@
+# Sharing disk space between VMs
+
+`vm rebase` makes a stopped VM store its identical disk blocks once with another VM's, or with a template's. Use it on machines restored without a template, or imported, to win back disk space.
+
+Two VMs restored separately from the same IPSW share nothing on disk, although much of their disk images is the same: two iOS 27.0 iPhones hold about 8.6 GB of identical bytes at the same places in their roughly 20 GB of data, mostly the system volume.
+
+## Rebase a VM
+
+1. Stop both machines. They must be on the same APFS volume.
+2. Check what a rebase would save:
+
+ ```sh
+ vphone-cli vm rebase second --onto first --dry-run
+ ```
+
+3. Rebase, onto a VM or onto a template:
+
+ ```sh
+ vphone-cli vm rebase second --onto first
+ vphone-cli vm rebase second --onto 3f2a91c0d4e7
+ ```
+
+`--onto` takes a VM name or a template identifier (or a unique prefix of one) from `vm template list`; a VM wins when a name matches both. `--dry-run` reports what would be shared and written without writing anything.
+
+The volume needs free space for the blocks that are written until the old image is released.
+
+## What it does
+
+The rebase rebuilds `second`'s disk image from an APFS clone of the base's and writes in only the blocks that differ. Every byte is compared with the original before the image is replaced, so the guest sees exactly the same disk.
+
+Only the disk image changes: `SEPStorage`, `nvram.bin`, `config.plist` and the device identity stay as they are. Rebasing onto a template leaves the template as it is, and the VM does not become one of its clones: `vm template show` does not list it.
+
+## Reading the result
+
+The saving is the **newly shared** figure. Bytes that are identical but already the same blocks on disk are reported as **already shared**, and rebasing them frees nothing.
+
+VMs made by `vm create` from one template already share its blocks, so rebasing one onto another, or onto that template, frees little. The command says so before it compares, and again when the saving is under 0.1 GB. The VMs worth rebasing are ones restored without a template (`--no-template`) or imported.
+
+## Things to know
+
+- The space comes back only when nothing else holds the old image's blocks. Snapshots of the VM, and clones made from it, keep them; delete those first or expect no saving.
+- `du` and Finder still count each image at its full size. Free space on the volume (`df`) is the honest measure.
+- The two images drift apart again as either VM writes to its disk. A base that is never booted, such as a template, stays the best base, and rebasing again later recovers what drifted.
+- A rebase that is interrupted leaves the VM unchanged and may leave a hidden `.rebase-*` folder in it; delete that folder.
+
+## See also
+
+- [Templates](templates.md)
+- [Snapshots](snapshots.md)
+- [Library, firmware and backups](library-and-backups.md)
diff --git a/Documents/en/storage/snapshots.md b/Documents/en/storage/snapshots.md
new file mode 100644
index 00000000..8cec9176
--- /dev/null
+++ b/Documents/en/storage/snapshots.md
@@ -0,0 +1,65 @@
+# Snapshots
+
+A snapshot saves a stopped machine's disk and boot state so you can return to it later. Take one after a clean install, try something destructive in the guest, then revert.
+
+## Take, list, revert and delete
+
+1. Stop the machine: `vphone-cli vm stop myphone`, or close it from its window.
+2. Take a snapshot, then work in the guest. When you want the saved state back, stop the machine again and revert.
+
+```sh
+vphone-cli vm snapshot create myphone clean --note "fresh install"
+vphone-cli vm snapshot list myphone
+vphone-cli vm snapshot revert myphone clean
+vphone-cli vm snapshot delete myphone clean
+```
+
+- `revert` and `delete` ask before they change anything; `--force` skips the question.
+- A revert keeps the snapshot, so you can go back to it again.
+- `list --json` prints an array of `{"name", "created", "note"}` objects, oldest first, with `created` in ISO 8601 and `note` left out when there is none.
+- `list` and `delete` work while the machine runs; neither touches its live files.
+
+## When create or revert refuses
+
+`create` and `revert` refuse while the machine is running, and while any process holds its disk image, `SEPStorage` or `nvram.bin` open. The refusal names each process holding them. When none of them runs the machine (a backup tool, Spotlight), it says so, and the retry succeeds once that process closes the files.
+
+`create` also refuses when the machine is not on an APFS volume, rather than copying a disk image that can be tens of gigabytes.
+
+A snapshot whose `Snapshot.plist` does not list all three state files, or lists a file that is not part of a snapshot, is refused as damaged before anything changes.
+
+A revert is all or nothing. If it fails partway, it puts the machine's own files back and reports the error, so the machine is as it was. In the rare case that putting them back fails too, the error says so: revert to a snapshot again before you start the machine.
+
+## What a snapshot holds
+
+| Captured | Why |
+| --- | --- |
+| The disk image (`Disk.img`) | The guest's system and data |
+| `SEPStorage`, `nvram.bin` | Secure Enclave state and the boot chain's NVRAM, which must match the disk |
+| `PatchReceipt.plist` | Which patches are live in the guest |
+| `restore-info.json` | The iOS version on the disk, and whether `cfw install` finished |
+
+The disk, `SEPStorage` and `nvram.bin` always move together. The Secure Enclave's anti-replay counters live in `SEPStorage`, and the disk holds the matching state; a disk from one moment with a `SEPStorage` from another makes the SEP panic on the next boot.
+
+`PatchReceipt.plist` and `restore-info.json` are taken when present. If one did not exist when the snapshot was taken, a revert removes it, so the records describe the restored disk rather than a later install.
+
+Not captured, and unchanged by a revert:
+
+- `config.plist`: the device identity, CPU, memory, network and other settings. Change them with `vm config` whenever you like; a revert does not undo that.
+- Patch choices (`PatchSelection.plist`), the restore tree, `FirmwareOriginals/` and the ROMs. These are inputs on the Mac, not guest state.
+- `launchpad.json`. Launchpad saves its own copy in the snapshot folder and puts it back itself. The CLI keeps any extra file in a snapshot folder untouched and deletes it with the snapshot.
+
+## Disk space
+
+Snapshots live in `<vm>/Snapshots/<name>/` as APFS clones. Taking one is instant and costs no space: the machine and its snapshots share every block until the guest writes to it, and then only the changed blocks take new space. `du` and Finder count each snapshot at the full size of the disk and overstate what it uses; free space on the volume is the honest measure.
+
+A snapshot keeps the disk blocks it was taken with. `vm rebase` frees nothing while a snapshot of that machine still holds the old blocks; see [Sharing disk space between VMs](sharing-disk-space.md).
+
+## Clones, exports, renames
+
+`vm clone` and `vm export` leave snapshots behind: a clone or an imported machine starts with none. Deleting or renaming a machine takes its snapshots with it.
+
+## See also
+
+- [Library, firmware and backups](library-and-backups.md)
+- [Sharing disk space between VMs](sharing-disk-space.md)
+- [Troubleshooting](../help/troubleshooting.md)
diff --git a/Documents/en/storage/template-building.md b/Documents/en/storage/template-building.md
new file mode 100644
index 00000000..80aedfd5
--- /dev/null
+++ b/Documents/en/storage/template-building.md
@@ -0,0 +1,118 @@
+# Building and finding templates
+
+How to finish a VM as a template by hand, how to ask which template a `vm create` would use, and how Launchpad builds templates. Read [Templates](templates.md) first for what a template is and what its key covers.
+
+## Finish a VM as a template
+
+To turn a VM into a template straight after creating it, stop it, trim it, give it the setup boot, and adopt it. This is what Launchpad does for a template it has to build:
+
+```sh
+vphone-cli vm stop phone-src
+vphone-cli vm template trim phone-src --tier standard # offline, no root; frees nothing until the setup boot
+vphone-cli vm template setup phone-src # headless; --window to watch, slimming switches as for vm create
+vphone-cli vm template adopt phone-src --iphone-source … --cloudos-source … # key from its records; the sources are recorded
+vphone-cli vm create phone-d --template <id> --skip-first-boot
+```
+
+### vm template setup
+
+- Refuses a running VM and a frozen template.
+- Trims nothing itself: it keeps the tier `vm template trim` recorded, and refuses a `--trim` that names another tier.
+- On a VM, it reports an app vphoned would not remove and leaves it out of the recorded steps, so the adopted key says what was really done.
+- `--strict` makes it fail instead; it records nothing, and you can run the setup boot again. Use it when the VM is to be adopted with `--expect` under the key `vm template find` gave for the same switches.
+- Given a `.building-…` name from `vm template list` (a `vm create` whose setup boot failed), it sets the build up to its key, which fixes the slimming, runs the offline trim first if the build stopped before it, and freezes it on success.
+
+### vm template adopt
+
+| Option | Effect |
+| --- | --- |
+| `--iphone-source`, `--cloudos-source` | Record the IPSWs the VM was created from in its `Template.plist`, as a `vm create` that builds a template does. |
+| `--json` | Print the new template as `vm template show --json` does. |
+| `--expect <id>` | Refuse, and leave the VM where it is, unless its records give the template identifier `<id>`: the `id` that `vm template find` printed for the options the VM was built with. |
+
+Use `--expect` whenever a template must be found again later. Without it, a VM whose setup boot fell short (an app it could not remove) would be saved under another key, and every later `vm create` with those options would miss it and build another template.
+
+The refusal names the fields that differ when it can work out the expected key, which it can when a template or build in the library has it or when only the slimming differs. Otherwise it prints the VM's own key to compare. With `--json` the refusal is also printed to stdout, and the command exits with status 1:
+
+```text
+{"adopted": false, "error": "unexpected_template", "id": …, "expected": …, "differences": […], …}
+```
+
+## Finding a template
+
+`vm template find` answers which template a `vm create` with the same options would clone from, without downloading, restoring or changing anything:
+
+```sh
+vphone-cli vm template find --iphone-source … --cloudos-source … [--device …] [--preset …] [--disk-size …] [--block <id>] [--allow <id>] [slimming switches] --json
+```
+
+It works out the key as `vm create` does. The builds come from the IPSWs when they are local files or already in the IPSW cache, and otherwise from a template whose record names the same two sources, so the key still resolves after the IPSWs are deleted, local ones included. `--block` and `--allow` are per-patch overrides as `fw set-patches` records them.
+
+| JSON field | Meaning |
+| --- | --- |
+| `resolved` | Whether the key could be worked out |
+| `resolvedBy` | `ipsw` or `template` |
+| `id` | The template identifier |
+| `summary` | The key summary |
+| `key` | The full key |
+| `template` | The matching template as `vm template show --json` prints it, current or stale |
+| `usable` | It exists and is current |
+| `building` | A create holds its build lock |
+| `reason` | Why the key is unresolved, when it is |
+
+## In Launchpad
+
+Launchpad 2.9 and later create machines from templates by default.
+
+### New Machine
+
+New Machine opens on a short page: the name, the device and iOS version from the firmware catalog, and a **Slim System** switch. A row below it sums up the rest and opens **Advanced Options**, four pages:
+
+- hardware;
+- the template and its parts: the trim tier and kept languages, the service profile, and which system apps go;
+- the Core Bundle, custom IPSWs and patches;
+- the location, network and restore options.
+
+The row counts the settings that differ from the defaults and names anything there that stops **Create**. Turning off **Create from a template** restores the machine on its own, as `--no-template` does, with keys of its own and without slimming. Apple Account is not offered: the guest refuses its sign-in either way, so Launchpad passes `--accounts-off` whenever the service profile is trimmed. The sheet grows with its page up to 600 points and scrolls past that, so its buttons stay on a laptop screen.
+
+### Firmware that rebuilds the kernelcache
+
+Under **Firmware**, a release that also runs on its own cloudOS (`fw catalog`'s third column) offers that cloudOS beside the recommended one. The creation then stages the kernelcache mix as you and has the helper link it as root, which asks for authorization once.
+
+Launchpad still shows an `ipsw` tool field for these pairings, for older compatible Core Bundles (2.12.0) that stage the mix with it. Core Bundle 2.12.1 and later extract natively and ignore the selected path.
+
+The iPhone XS Max runs iOS 18.1 to 18.7.2, each on its own release's cloudOS, with no template and the Minimal preset by default; Standard works as well (checked on 18.6). Its pairings always rebuild the kernelcache, so **Firmware** also asks for the macOS builder:
+
+- `user@host` of a Mac or macOS VM running macOS 15 or 26.0 to 26.3 with Remote Login on;
+- its password for ssh and sudo, empty with ssh keys and passwordless sudo.
+
+Launchpad keeps the builder, but not the password, which reaches `vphone-cli` only in its environment (`VPHONE_KMUTIL_SSH_PASSWORD`). The creation then stages and links the mix as you, over ssh. From macOS 26.4 on the builder is required; on an older Mac without one, the helper links the mix as root.
+
+### How the creation uses templates
+
+The creation runs `vm template find` first.
+
+- When a current template matches, it clones the machine (`vm create --template <id> --skip-first-boot`) and boots it.
+- When none does, it builds the template in a temporary machine of the same library, named `template-` and eight hex digits. It runs the usual steps (restore, then `cfw install` through the helper), then `vm template trim`, the headless `vm template setup --strict`, and `vm template adopt --iphone-source … --cloudos-source … --expect <id>`, and clones the machine from the result.
+
+The setup boot fails when an app it should remove stays, and the adopt fails when the build's key differs from the one `find` computed, so a build is never saved under an id later creations would not find. Each is a step of its own with its duration, and a failed one shows the reason `vphone-cli` gave.
+
+Per-patch overrides from New Machine's **Patch Settings** split the way the template key splits them:
+
+- Boot-chain overrides are part of the key: the template is built with them, and `find` looks for one with them.
+- Guest patch overrides are not: the template is built without them. After the clone, the creation records them on the new machine with `fw set-patches` and writes them with `cfw update-environment` through the helper (the **Apply guest patches** step) before its first boot. A template therefore never hands one creation's guest patch choice to another.
+
+Once it has built a template, the creation offers to delete the two IPSWs it came from; nothing is deleted without confirmation.
+
+### Managing templates in Launchpad
+
+- **File > Templates…** lists every library's templates with their machines, slimming, size and state, and deletes them.
+- **Guest System…** (in a machine's Actions menu and inspector) switches a running machine's service profile and restores system apps the template removed.
+- The inspector and the machine list show each machine's exclusive disk use beside what its files allocate: the blocks no other machine or template holds, which deleting it frees. A local Time Machine snapshot taken before keeps them until it expires.
+
+## See also
+
+- [Templates](templates.md)
+- [Create many machines](many-machines.md)
+- [Firmware preparation](../firmware/firmware-preparation.md)
+- [Launchpad CLI](../launchpad/launchpad-cli.md)
diff --git a/Documents/en/storage/templates.md b/Documents/en/storage/templates.md
new file mode 100644
index 00000000..0be34eb9
--- /dev/null
+++ b/Documents/en/storage/templates.md
@@ -0,0 +1,162 @@
+# Templates
+
+A template is a complete, frozen machine that `vm create` clones new machines from. The first creation with a given set of options builds it; every later one with the same options takes seconds and downloads nothing. Read this page to control how templates are built, slimmed and cleaned up.
+
+## Create machines from a template
+
+`vm create` uses templates by default:
+
+```sh
+vphone-cli vm create phone-a --iphone-source … --cloudos-source … # builds the template, clones phone-a
+vphone-cli vm create phone-b --iphone-source … --cloudos-source … # clones phone-b, no restore
+vphone-cli vm create phone-c --template 3f2a91c0d4e7 --cpu 4 --memory 6144
+```
+
+- With a matching template, `vm create` clones the machine from it with a new identity, gives it the requested CPU, memory and network, and boots it once to check vphoned. This needs neither root nor the IPSWs.
+- Without one, it downloads the IPSWs if needed, runs the full pipeline into a staging folder, builds and freezes the template, then clones the machine from it.
+- `--template <id>` clones from a template by its identifier, or a unique prefix of four or more digits, and takes no IPSW options. `--device`, `--preset`, `--disk-size` and the slimming switches, when given, must match the template's; a clone cannot change them.
+- `--no-template` restores the machine on its own, with keys of its own; it takes no slimming switches.
+
+To turn a VM into a template by hand, ask which template a `vm create` would use, or see how Launchpad builds them, read [Building and finding templates](template-building.md).
+
+## How a template is matched
+
+Before anything is restored, `vm create` works out a template key from its options and the two IPSWs. The key covers:
+
+- the guest device;
+- the iOS and cloudOS versions and builds;
+- the patch preset and the boot-chain patches it resolves to. For a preset the bundle does not ship (a preset file, or one in `~/.vphone/patches_presets`), every patch it resolves to counts, guest ones included, because such a preset can change under the same identifier and a clone keeps its template's guest patches;
+- the bundle series (`2.9` for 2.9.x);
+- the disk size;
+- what is trimmed from the guest's System volume (`--trim`) and the kept languages;
+- the slimming switches below.
+
+CPU, memory, screen and network are not part of the key.
+
+The builds come from the IPSWs when they are local files or already in the IPSW cache. Otherwise they come from a template recorded with the same two sources, as [`vm template find`](template-building.md#finding-a-template) works them out; a local IPSW that has been deleted counts as not there.
+
+### Building a template
+
+When no template matches, the full pipeline runs into `.templates/.building-<id>-<uuid>/`: `cfw install`, the offline trim, then the setup boot. The result is frozen and renamed to `<library>/.templates/<id>/` in one step.
+
+- The restore tree is removed before the freeze, whatever `--keep-artifacts` says. Its ~11 GB would stay pinned for as long as the template lives, and no clone can use it. `--keep-artifacts` keeps it only with `--no-template`; `vm template adopt` removes it too.
+- A second `vm create` with the same key waits for the first instead of restoring a second copy.
+- A failed build stays in its staging folder for inspection.
+
+A template boots once while it is built, for its setup boot, and never again once it is frozen.
+
+## Offline trim
+
+After `cfw install`, a template build deletes system files the guest never needs from its System volume, offline, with the volume mounted on the host. `--trim` on `vm create` (default `standard`) and `--tier` on `vm template trim` pick the tier:
+
+| Tier | Deletes | About |
+| --- | --- | --- |
+| `none` | nothing | |
+| `conservative` | the contents of `usr/standalone/update` (software-update ramdisk, baseband firmware) | 0.35 GB |
+| `standard` | conservative, plus the AirPods/Beats pairing assets (`PreinstalledAssetsV2/RequiredByOs/com_apple_MobileAsset_SharingDeviceAssets`), the watch faces (`NanoTimeKit/FaceBundles`) and the `LinguisticData/RequiredAssets_*.bundle` of every language not kept | 1.2 GB |
+| `aggressive` | reserved: refused until it has been validated on a guest | |
+
+`--keep-languages` (default `en,zh-Hans,zh`; English is always kept) chooses the languages `standard` keeps. The tier, the version of the list and the kept languages are part of the template key (`standard/1/en,zh,zh-Hans`), so templates trimmed differently never match.
+
+> [!WARNING]
+> Trimming cannot be undone: a clone cannot get the files back.
+
+The deleted files free nothing at first. The guest's original system snapshot (`orig-fs.disabled.rn-*`, left by `cfw install`) still holds every block, and the host cannot delete it, even as root. The setup boot deletes it as its first step, and only then is the space returned. So a trim is refused for a template that gets no setup boot, and a trimmed template is frozen or adopted only once its snapshot is gone.
+
+`vm template trim` needs no root. It runs on a stopped machine that has not been cloned from a template, or on an unfinished `.building-…` folder, and refuses a frozen template.
+
+## Setup boot and slimming
+
+The setup boot finishes the template the way every clone should start. It boots the template once and, through vphoned, in this order:
+
+1. deletes the `orig-fs.disabled.rn-*` APFS snapshot `cfw install` left (it holds about 20 MB, plus every file trimmed from the System volume until it is gone);
+2. skips Setup Assistant (`setup.skip`);
+3. waits for first-boot work to settle (`setup.settle`, up to 10 minutes): installd expands the removable system apps on the first boot;
+4. removes the system apps (`apps.remove_system`, backups kept in the guest);
+5. applies the service profile (`services.profile.apply`), which includes turning off the sign-in follow-up daemons (`followupd`, `appleidsetupd`);
+6. reboots, then checks: no snapshot left, Setup done, none of the profile's services running, the removed apps gone, vphoned answering;
+7. clears the device name `vphone-vm` pinned for this boot, and shuts the guest down cleanly.
+
+Every step has a deadline. A failed step stops the VM, records nothing and leaves the build unfrozen; `vm create` names the step and how to retry it.
+
+| Switch | Default | Effect |
+| --- | --- | --- |
+| `--slim on\|off` | on | `off` trims nothing and keeps every app and service. The setup boot still runs: Setup is skipped and the snapshot deleted. |
+| `--trim none\|conservative\|standard` | standard | The offline trim above. |
+| `--keep-languages <list>` | `en,zh-Hans,zh` | The languages `--trim standard` keeps. |
+| `--service-profile trimmed\|none` | trimmed | vphoned's trimmed profile: about 140 launchd jobs off, the App Store daemons and sign-in follow-up among them. A phone with this profile cannot pair an Apple Watch (see `Research/Guest/watch_pairing.md`). |
+| `--remove-apps on\|off` | on | Removes App Store, Home, TV, News, FaceTime, iTunes Store, Messages, Games, Find My and Wallet. Camera and Phone stay. |
+| `--keep-apps <ids>` | none | Bundle IDs from that list to keep, comma-separated (`com.apple.findmy,com.apple.Passbook`). |
+| `--accounts-off` | off | Also turns off `akd`, `amsaccountsd` and `appleaccountd`. The guest then cannot sign in to an Apple Account. |
+
+Each choice is part of the key, so templates with different slimming live side by side and each serves only the creates that ask for it. See [the watch pairing note](../../../Research/Guest/watch_pairing.md) for the service-profile limit.
+
+Removed apps and the profile stay reversible on a clone, through `vphone-launchpad-cli guest rpc` or **Guest System** in Launchpad:
+
+- `apps.restore_system` puts an app back from its backup.
+- `services.profile.apply {"profile":"none"}` turns back on exactly what the profile turned off.
+
+### What a clone inherits
+
+A clone inherits from the template: Setup done, the apps and services as the setup boot left them, the first-boot work installd and the indexers did, and the Data volume as of that boot.
+
+It does not inherit a device name. The template's pin is cleared, so a clone shows `iPhone` until its own VM connects and pins the clone's name. A new identity also means the Mac asks "Trust This Computer?" again.
+
+## Shared secrets
+
+> [!WARNING]
+> Every machine cloned from one template shares, with the template and with each other, its SEP root secret, its Data volume keys and the data the restore and the setup boot wrote. One clone could in principle decrypt another's Data volume.
+
+A machine that needs keys of its own, for example to sign in to Apple services for multi-device research, should be created with `--no-template`.
+
+Clones get a new ECID, UDID and MAC address on their first start, as with `vm clone --new-identity`. On APFS they share every unchanged block with the template: a new clone costs almost nothing until it starts writing, and a slimmed template leaves it little first-boot work to write.
+
+## Manage templates
+
+```sh
+vphone-cli vm template list # id, key summary, STALE with the reasons
+vphone-cli vm template show <id> --json
+vphone-cli vm template trim myphone --tier standard # trim a stopped VM before adopting it
+vphone-cli vm template setup myphone # the setup boot, on a stopped VM
+vphone-cli vm template adopt myphone # freeze a stopped, newly created VM into a template
+vphone-cli vm template delete <id>
+```
+
+### Stale templates
+
+A template is listed as stale when this `vphone-cli` belongs to another bundle series, when its key has an older format, when its preset now resolves to other boot-chain patches, or when its patch receipt disagrees with its plan. A stale template is never used: `vm create` with its key fails and names it. Delete it to have the next `vm create` build a new one.
+
+### Adopting a VM
+
+`vm template adopt <vm>` turns a stopped VM into a template, under the key its own records give: `restore-info.json`, `PatchPlan.plist`, `config.plist`, the disk image, Launchpad's `launchpad.json`, and the steps `vm template trim` and `vm template setup` recorded in its `Template.plist`. The VM leaves `vm list`.
+
+Adopt a VM straight after its setup boot: every clone inherits what its guest has done since. A VM with snapshots is refused, and so is one that would be stale unless `--force` is given.
+
+### Frozen templates never boot
+
+`vm launch` and `vphone-vm` refuse a frozen template, in DFU too. No machine name reaches into `.templates`, so `vm launch`, `clone`, `export`, `rename` and `delete` cannot pick one up by accident. A template that booted after being frozen would write state into the blocks every later clone inherits, and the clones made before it would stop sharing them.
+
+### Machines using a template
+
+A machine cloned from a template records the template in `TemplateSource.plist`. A `vm clone` of it keeps the record (the copy shares the template's blocks too), and `vm export` leaves it out (an import shares nothing). The record also names the template's build, so a template deleted and built again with the same key does not count the machines cloned from the old one, which share none of its blocks.
+
+`vm template list` and `show` list the machines using each template and its size on disk, and `vm info` shows a machine's template. When `vm delete` removes the last machine cloned from a template that still exists, it says so, and never deletes the template itself:
+
+```text
+note: template 3f2a91c0d4e7 (~17.40 GB) is no longer used by any machine; remove it with `vphone-cli vm template delete 3f2a91c0d4e7`
+```
+
+### Deleting a template
+
+`vm template delete <id>` removes the template; machines cloned from it keep working. The blocks they still share with it are freed only when those machines change them or are deleted, so deleting a template frees less than its size while clones remain.
+
+The note it prints says which case applies: either the machines that use it, whose shared blocks stay allocated until they change them or are deleted, or that no machine uses it now, so deleting frees its blocks. A local Time Machine snapshot taken while the template existed may keep them until the snapshot expires. `--json` with `--force` prints the same facts.
+
+Templates take disk space although `vm list` does not show them. Look in `~/.vphone/machines/.templates`, and keep in mind that `du` counts a template and each of its clones in full.
+
+## See also
+
+- [Building and finding templates](template-building.md)
+- [Create many machines](many-machines.md)
+- [Sharing disk space between VMs](sharing-disk-space.md)
+- [Library, firmware and backups](library-and-backups.md)
diff --git a/Documents/ja/README.md b/Documents/ja/README.md
new file mode 100644
index 00000000..1cc7e83e
--- /dev/null
+++ b/Documents/ja/README.md
@@ -0,0 +1,70 @@
+# vphone マニュアル
+
+vphone を初めて使う場合は、[概要](get-started/overview.md)を読んでから[クイックスタート](get-started/quick-start.md)の手順に従ってください。
+
+## はじめに
+
+| ページ | 内容 |
+| --- | --- |
+| [概要](get-started/overview.md) | vphone の概要、必要な環境、同梱されるプログラム |
+| [クイックスタート](get-started/quick-start.md) | Launchpad またはコーディングエージェントで最初の仮想マシンを作る |
+| [ホストの設定](get-started/host-setup.md) | Mac の SIP、AMFI、Research Guests の設定 |
+| [ダウンロード](get-started/downloads.md) | 公証済みの Launchpad バージョンと対応する `VPhone.bundle` バージョン |
+
+## マシン
+
+| ページ | 内容 |
+| --- | --- |
+| [作成と実行](machines/create-and-run.md) | ターミナルでの仮想マシンの作成、起動、停止 |
+| [ブート ROM](machines/boot-roms.md) | OpenAVB/OpenSEP と Apple の ROM の切り替え |
+| [自動化 API](machines/automation-api.md) | 任意で有効にできるローカルの HTTP と WebSocket インターフェース |
+| [デバイス名と時計](machines/device-name-and-clock.md) | ゲストが仮想マシン名と Mac の時計から受け取るもの |
+| [パッケージ環境](machines/package-environment.md) | ゲストへのパッケージマネージャのインストールと削除 |
+
+## ファームウェアとデバイス
+
+| ページ | 内容 |
+| --- | --- |
+| [互換性](firmware/compatibility.md) | 検証済みの iPhone と cloudOS のファームウェアの組み合わせ |
+| [ファームウェアの準備](firmware/firmware-preparation.md) | GPU ドライバの復元、新しい cloudOS 向けの kernelcache ミックス |
+| [その他の iPhone モデル](firmware/iphone-models.md) | 別の iPhone モデルの IPSW で iOS を実行する |
+| [iPadOS ゲスト](firmware/ipados.md) | iOS の代わりに iPadOS を実行する |
+
+## ストレージとバックアップ
+
+| ページ | 内容 |
+| --- | --- |
+| [ライブラリとバックアップ](storage/library-and-backups.md) | 仮想マシンとキャッシュの保存場所、複製と書き出し |
+| [スナップショット](storage/snapshots.md) | 停止中の仮想マシンのディスクを保存し、その状態に戻す |
+| [テンプレート](storage/templates.md) | 1 回の復元を複数の仮想マシンで再利用する |
+| [テンプレートの作成](storage/template-building.md) | 仮想マシンをテンプレートにする方法とテンプレートの検索 |
+| [ディスク容量の共有](storage/sharing-disk-space.md) | 別々に復元した仮想マシンに使う `vm rebase` |
+| [複数マシンの一括作成](storage/many-machines.md) | plist から実行する `vm create-bulk` |
+| [シェーダキャッシュ](storage/shader-cache.md) | 既存の仮想マシンでの永続シェーダキャッシュ |
+
+## ネットワーク
+
+| ページ | 内容 |
+| --- | --- |
+| [ネットワークモード](networking/overview.md) | モードの選択、実行中の仮想マシンのネットワーク切断 |
+| [トンネルモード](networking/tunnel.md) | VPN やプロキシアプリを使っている Mac |
+| [MAC アドレスと IP アドレス](networking/addresses.md) | 保存された MAC、古いリース、固定アドレス |
+| [ポート転送](networking/port-forwarding.md) | Mac のポートをゲストに転送する |
+| [ネットワーク上の名前](networking/names.md) | ゲストの `.local` 名と、ゲスト内での Mac の名前 |
+| [マシン同士の通信](networking/peers.md) | 1 つの共有ネットワーク上の `nat` マシン |
+
+## Launchpad とバンドル
+
+| ページ | 内容 |
+| --- | --- |
+| [Launchpad コマンドライン](launchpad/launchpad-cli.md) | `vphone-launchpad-cli` で Launchpad を操作する |
+| [Core Bundle とローカルビルド](launchpad/core-bundles.md) | マシンとバンドルの紐付け、ローカルビルドのテスト |
+| [バンドルの組み込み](launchpad/bundle-integration.md) | `VPhone.bundle` の中身と、アプリからの使い方 |
+
+## ヘルプ
+
+| ページ | 内容 |
+| --- | --- |
+| [トラブルシューティング](help/troubleshooting.md) | 起動の拒否、復元の失敗、ゲストの問題 |
+
+実装メモ、パッチの記録、API の完全なリファレンスは[研究記録](../../Research/README.md)にあります(英語のみ)。
diff --git a/Documents/ja/firmware/compatibility.md b/Documents/ja/firmware/compatibility.md
new file mode 100644
index 00000000..c9ca5b57
--- /dev/null
+++ b/Documents/ja/firmware/compatibility.md
@@ -0,0 +1,166 @@
+# ファームウェアの互換性
+
+どのゲストファームウェアと cloudOS の組み合わせが、どのホストで起動することが確認されているかをまとめています。新しいマシンのリリースを選ぶ前や、作成に失敗してその組み合わせがテストされたことがあるかを知りたい場合にご覧ください。
+
+現在のカタログでこの Mac に提供されるものを確認するには、次を実行します。
+
+```sh
+vphone-cli fw catalog
+```
+
+> [!NOTE]
+> v2.0.0 以降、vphone は `config.plist` が `schemaVersion=2` のマシンだけを起動します。以前のリリースで作成したマシンは `vm create` で作り直してください。その場でのアップグレードはありません。以下の結果はテスト済みの組み合わせを示すもので、古いマシンバンドルとの互換性を示すものではありません。
+
+## テスト済みの環境
+
+ネイティブの JB パイプラインで最初から最後まで実行した iPhone17,3 の組み合わせです。PR #486 の 2 行([PR #486](https://github.com/Lakr233/vphone-cli/pull/486))はロック画面に到達し、vphoned の ping に応答しました。新規に実行した 26.6.2 の `vm create` もすべての段階を完了し、初回起動の ping の後に正常終了しました。
+
+| 検証 | iPhone 復元用 IPSW | PCC/cloudOS IPSW | 確認された結果 |
+| --- | --- | --- | --- |
+| PR #486 | `17,3_26.6.2_23G90` | `26.4-23E5207q` | JB パッチ、復元、CFW、起動、vphoned の ping |
+| PR #486 | `17,3_27.0_24A435` | `26.4-23E5207q` | JB パッチ、復元、CFW、起動、vphoned の ping |
+| 研究用ボード | `17,3_26.6_23G71` | `26.6-23G71` | CLI から standard と Minimal プリセット、Launchpad から standard(2026-10-20):デバイスツリーと SEP の変換、kernelcache ミックス、復元、CFW、起動、vphoned の ping |
+| 研究用ボード | `17,3_26.5_23F77` | `26.5-23F75` | CLI から standard プリセット(2026-10-20):一時的な cloudOS の復元から GPU ドライバ、kernelcache ミックス、復元、CFW、起動、vphoned の ping |
+| 研究用ボード | `17,3_26.4_23E246` | `26.4-23E244` | CLI から standard プリセット(2026-10-20):一時的な cloudOS の復元から GPU ドライバ、kernelcache ミックス、復元、CFW、起動、vphoned の ping |
+| 研究用ボード | `Watch7,18_26.4_23T240` | `26.4-23E244` | CLI と Launchpad から `watchos` プリセット(2026-10-20):Watch の kernelcache ミックス、復元、起動、vphoned の ping |
+| 研究用ボード | `11,6_18.7.2_22H124` | `18.7.2-22H43` | CLI から Minimal プリセット(2026-10-21):一時的な cloudOS の復元から GPU ドライバ、macOS 15.6.1 の kmutil で ssh 経由でリンクした iOS 18 の kernelcache ミックス、復元、起動、vphoned の ping。画面、ロック画面、ロック解除、ホームへのスワイプを確認 |
+| 研究用ボード | `11,6_18.1_22B83` | `18.1-22B83` | CLI から Minimal プリセット(2026-10-21):一時的な cloudOS の復元から GPU ドライバ、macOS 15.6.1 の kmutil で ssh 経由でリンクした kernelcache ミックス、復元、起動、vphoned。「こんにちは」画面、ロック画面、ロック解除、ホームへのスワイプを確認 |
+| 研究用ボード | `11,6_18.5_22F76` | `18.5-22F76` | CLI から Minimal プリセット(2026-10-21):一時的な cloudOS の復元から GPU ドライバ、macOS 15.6.1 の kmutil で ssh 経由でリンクした kernelcache ミックス、復元、起動、vphoned。ロック画面、ロック解除、ホームへのスワイプを確認 |
+| 研究用ボード | `11,6_18.6_22G86` | `18.6-22G86` | Launchpad の CLI から standard プリセット(2026-10-24):kernelcache ミックス(キャッシュ済み)、復元、CFW、起動、vphoned、「こんにちは」画面。2 つの Frida パッチを許可した状態で Frida 17.24.3 の attach、spawn、Interceptor、Stalker |
+
+### どの cloudOS を使うか
+
+特に理由がなければ、cloudOS 26.4 ベータ(`26.4-23E5207q`)を使ってください。これは `vphone600ap` を含む最新の cloudOS です。`vphone600ap` は、ゲストのカーネル、SEP、デバイスツリーの元になるアイデンティティです。また、`vphone-cli` 以外に何も必要としません。
+
+それ以降の cloudOS(2026-10-03 に確認)には PCC のボードと `vresearch101ap` しかありません。`SupportedProductTypes` から `iPhone99,11` がなくなり、`kernelcache.*.vphone600`、`sep-firmware.vphone600`、`DeviceTree.vphone600ap` もありません。このような cloudOS では、研究用ボード(Research Board パッチセット)が代わりを務めます。
+
+- `fw patch` は、研究用ボードのデバイスツリーと SEP を vphone600 のものに変換し、その kernelcache 用のレシピに従って、vphone600 の仮想化 kext を加えて kernelcache を作り直します。
+- KDK の展開はネイティブで行われ、root が必要なのはリンクだけです(`vphone-cli fw kernelcache`)。[kernelcache のレシピ](../../../VPhoneExecutable/VPhoneVirtualization/Resources/kernelcache_recipes/README.md)と[ファームウェアの準備](firmware-preparation.md)をご覧ください。
+- `fw prepare` は、どのレシピにも該当しない cloudOS を拒否します。
+- `fw catalog` は各 iOS リリースに対応する cloudOS を推奨の cloudOS と並べて表示し、Launchpad では **Firmware** でそれを選べます。
+
+| cloudOS | `vresearch101ap` | `vphone600ap` | kernelcache のレシピ |
+| --- | --- | --- | --- |
+| `26.4-23E5207q`(ベータ) | あり | あり | 不要 |
+| `26.4-23E244` | あり | なし | あり |
+| `26.4.1-23E254` | あり | なし | なし |
+| `26.5-23F75` | あり | なし | あり |
+| `26.5.2-23F83` | あり | なし | なし |
+| `26.6-23G71` | あり | なし | あり |
+| `26.6.1-23G82` | あり | なし | なし |
+| `26.7-23H20` | あり | なし | あり |
+
+ほかのバージョンの iPhone と iPad も `26.4-23E5207q` で動作する可能性がありますが、同じエンドツーエンドのチェックは通過していません。
+
+### iOS 18 ゲスト
+
+iOS 18.1〜18.7.2 は、それぞれのリリースに対応する cloudOS 上で、iPhone XS ファミリーの IPSW のユーザランドを使って動作します。
+
+- `vm create --device iPhone11,6` で作成します。既定のプリセットは Minimal です。`--preset standard` は 18.6 で確認済みです。
+- `fw catalog --device iPhone11,6` でリリースの一覧を表示できます。
+- これらのカーネルは kernel-first です。macOS 26.4 以降では、macOS 15 または 26.0〜26.3 を実行している別の Mac または macOS 仮想マシンが ssh 経由でミックスをリンクします(`VPHONE_KMUTIL_SSH`。[ファームウェアの準備](firmware-preparation.md)をご覧ください)。
+- Launchpad では iPhone XS Max として表示され、その Mac を macOS ビルダーとして使います。
+
+18.1、18.5、18.7.2 は仮想マシンで確認済みです。残りの 4 つのレシピはまだ起動していません。
+
+### iOS 27.0.1 の iPhone17,3
+
+iOS 27.0.1(24A446)は、バンドル 2.5.0 以前では初回起動に失敗します(2026-10-04 に再現、Apple の未変更の launchd でも同様)。TXM の selector-24 の事前チェックが init の時点ですべてのバイナリを拒否し、`unexpected SIGKILL of init` でパニックします。`txm-boot-precheck_admission` パッチでこれが修正されます([研究記録](../../../Research/Firmware/txm_selector24_cms_gate.md)をご覧ください)。このパッチを使うと、`26.4-23E5207q` 上の iPhone17,3 27.0.1 はゲストまで起動し、vphoned の `device.info` に応答します(同日に検証)。このパッチを含む最初のリリースはバンドル 2.6.0 です。
+
+## macOS 26.6.2 のホスト
+
+2026-10-23 に Core Bundle 2.12.1 で、2026-10-24 に Core Bundle 2.12.2 で、Mac mini M4 のホスト(Mac16,10、16 GB、macOS 26.6.2 25G83)で確認しました。すべてのマシンを CLI から新規に作成しました。研究用ボードの組み合わせでは、kernelcache ミックスをユーザとして準備して sudo でリンクし、その後 `sudo vphone-cli vm create` を実行しました。「標準」は、この Mac で `fw catalog` がそのデバイスに示す最新の組み合わせで、Launchpad の New Machine が選ぶものです。その後、各マシンをヘッドレスで 2 回起動し、vphoned が応答すること、`device.info` がリリースを報告すること、ゲストのシリアルログにパニックがないことを確認しました。
+
+| ゲスト | ファームウェア | cloudOS | 結果 |
+| --- | --- | --- | --- |
+| iPhone17,3 | iOS 27.0.1(標準) | `26.4-23E5207q` | テンプレートの作成、複製、2 回の起動 |
+| iPhone18,2 | iOS 27.0.1(標準) | `26.4-23E5207q` | テンプレートの作成、複製、2 回の起動 |
+| iPad16,1 | iPadOS 27.0.1(標準) | `26.4-23E5207q` | テンプレートの作成、複製、2 回の起動 |
+| iPhone17,3 | iOS 26.6.2 | `26.4-23E5207q` | テンプレートの作成、複製、2 回の起動 |
+| iPhone17,3 | iOS 26.6.2 | `26.6-23G71` | 研究用ボード:ネイティブの KDK 展開、auth スタブの残らない macOS 26 でのリンク、28 個の kernelcache パッチ、2 回の起動 |
+| iPhone17,3 | iOS 26.5 | `26.5-23F75` | 研究用ボード、上と同じ |
+| iPhone17,3 | iOS 26.4 | `26.4-23E244` | 研究用ボード、上と同じ |
+| iPhone17,3 | iOS 18.6.2 | `26.1-23B85` | テンプレートの作成、複製、2 回の起動 |
+| iPhone11,6 | iOS 18.7.2(標準) | `18.7.2-22H43` | Minimal、macOS 15.7.7 仮想マシンの kmutil で ssh 経由でリンクしたミックス、2 回の起動 |
+| iPhone11,6 | iOS 18.6 | `18.6-22G86` | 上と同じ:このレシピの初めての起動 |
+| iPhone11,6 | iOS 18.7 | `18.7-22H20` | 上と同じ:このレシピの初めての起動 |
+| Watch7,18 | watchOS 26.4(標準) | `26.4-23E244` | `watchos` プリセット、Watch の kernelcache ミックス、2 回の起動 |
+| AppleTV5,3 | tvOS 26.6(標準) | `26.4-23E5207q` | `tvos` プリセット、2 回の起動 |
+| AppleTV14,1 | tvOS 26.6(macOS 26 での標準) | `26.4-23E5207q` | `tvos-4k` プリセット、26.6 の OTA のユーザランド、2 回の起動 |
+| AudioAccessory5,1 | HomePod ソフトウェア 27.0(macOS 26 での標準) | `26.4-23E5207q` | `homepod-mini` プリセット、2 回の起動 |
+| AppleTV14,1 | tvOS 27.0 | — | ダウンロード前に拒否:macOS 27 が必要 |
+| AudioAccessory5,1 | HomePod ソフトウェア 27.2 | — | ダウンロード前に拒否:macOS 27 が必要 |
+
+tvOS 27.0(24J361)と HomePod ソフトウェア 27.2(24K120)の OTA はペイロードを LZRAVEN で圧縮しており、これを展開できるのは macOS 27 だけです。古い Mac では `fw catalog` がこれらを除外するため、それらのデバイスでの Launchpad の標準は tvOS 26.6 と HomePod ソフトウェア 27.0 になり、これらのバージョンを指定すると何もダウンロードされないうちに拒否されます。
+
+Apple TV 4K(第 4 世代)、`AppleTV18,1` / `J265AP` は、立ち上げ作業用としてのみ、tvOS 27.2 ベータ(`24K120`)で利用できます。Apple TV HD 26.6 の復元ベースと cloudOS 26.4 ベータ(`23E5207q`)の上に、そのフル OTA を重ねて使います。macOS 27 と `tvos-4k` プリセットが必要です。2026-10-24 に 1 台のマシンを復元してカスタムファームウェアをインストールし、2 回コールドブートして、vphoned と旧 TVSetup の 4K 言語選択画面まで到達しました。セットアップ自体は完了していません。上のテスト済みの表には含まれていません。[立ち上げの記録](../../../Research/Firmware/tvos_support.md#apple-tv-4k-4th-generation)をご覧ください。
+
+cloudOS 26.7(23H20)には組み合わせられる iPhone のリリースがありません。iOS 26.6.2 のユーザランドで準備すると、ミックスはリンクでき 28 個の kernelcache パッチも適用されますが、CFW パッチ `_vm_fault_enter_prepare` がそのカーネルで適用箇所を見つけられません。起動はしていません。
+
+> [!TIP]
+> `vphone-escalator` は許可リストを amfid のメモリに保持するため、amfid が再起動すると許可リストは失われます。これらのホストでも、実行中に一度そうなりました。Launchpad は、AMFI がバンドルを拒否すると再び許可します。CLI からの場合は、`host preflight` が表示する `vphone-escalator allow` コマンドをもう一度実行してください。
+
+## その他の iPhone モデル
+
+iPhone17,3 以外のモデルについては[その他の iPhone モデル](iphone-models.md)をご覧ください。
+
+| ホスト | iPhone 復元用 IPSW | PCC/cloudOS IPSW | 確認された結果 |
+| --- | --- | --- | --- |
+| Mac17,9 (M5 Pro) 27.0.1 | `18,1_26.6.2_23G90` (iPhone 17 Pro) | `26.4-23E5207q` | Launchpad の `vm create`(2.5.1 のローカルバンドル):準備、パッチ、復元、CFW、402x874 pt @3x のホーム画面まで起動、`model` iPhone18,1、vphoned の ping |
+| Mac17,9 (M5 Pro) 27.0.1 | `18,2_27.0.1_24A446` (iPhone 17 Pro Max) | `26.4-23E5207q` | `kernel-boot-shared_region_size` パッチで**起動**(2026-10-06、バンドル 2.6.0-local.0d5e6f90):`dyld cache mapped system-wide`、パニック 0 回、vphoned が 27.0.1 として応答、440x956 pt @3x のホーム画面 |
+| Mac17,7 (M5 Max) 26.4 | `19,2_27.0.1_24A446` (iPhone 18 Pro) | `26.4-23E5207q` | ARM64E_X1 互換機能を統合して**起動**(2026-10-17):オフラインでの問題のない復元、ルートシールの検証、vphoned の ping、設定、Safari、計算機の起動 |
+
+### iOS 27 の iPhone18,1 と iPhone18,2
+
+これらには `kernel-boot-shared_region_size` パッチが必要です([issue #596](https://github.com/Lakr233/vphone-cli/issues/596)、27.0 と 27.0.1)。2026-10-06 以降、iOS 27 ベースでは `standard` プリセットでオンになっています。
+
+27.0.1 のこれらの dyld 共有キャッシュは `sharedRegionSize` が `0x185804000` で、cloudOS 26.4 のゲストカーネルの共有領域 `0x180000000` より大きいため、`dyld-boot-maxslide` でスライドをなくしてもキャッシュをマップできません。パッチがないと、launchd が初回起動時に `Library not loaded: /usr/lib/libSystem.B.dylib` でパニックします。iPhone17,3 の 27.0.1 のキャッシュ(`0x17D508000`)はまだ収まります。
+
+このパッチは arm64 の領域を `0x1C0000000` に広げます。これは 26.4 カーネル自身のタスクマップの上限を超えない最大のサイズです。マシンのカーネルにこのパッチが含まれている場合(`PatchReceipt.plist` に記録されています)、`cfw install` は広げた領域を基準にキャッシュを測るため、これらのデバイスはインストールして起動できます。これは上のとおり iPhone18,2 27.0.1 で検証済みです。
+
+パッチがない場合(古いバンドル、またはパッチのチェックを外した場合)、`cfw install` はパニックするゲストを残す代わりに、この説明を付けてそのようなキャッシュを拒否します。iOS 27 には iPhone17,3 を使うか、これらのデバイスでは iOS 26 を使ってください。
+
+## iPadOS
+
+iPad ゲストについては [iPadOS ゲスト](ipados.md)をご覧ください。
+
+| ホスト | iPad 復元用 IPSW | PCC/cloudOS IPSW | 確認された結果 |
+| --- | --- | --- | --- |
+| Mac17,9 (M5 Pro) 27.0.1 | `iPad16,1,iPad16,2_26.6.2_23G90` | `26.4-23E5207q` | 準備、パッチ、復元、CFW(2.2.5 のヘルパー)、744x1133 pt @2x の iPadOS ホーム画面まで起動、`model` iPad16,1、vphoned の ping |
+| Mac17,9 (M5 Pro) 27.0.1 | `iPad16,1,iPad16,2_27.0.1_24A446` | `26.4-23E5207q` | カタログからの Launchpad の `vm create --device iPad16,1`(2.4.0 のバンドル):準備、パッチ、復元、CFW、744x1133 pt @2x の iPadOS ホーム画面まで起動、`model` iPad16,1、`ios_version` 27.0.1、vphoned の ping |
+
+## 以前に報告された組み合わせ
+
+以前の README には、次のホストとファームウェアの組み合わせが記録されていました。これらは現在の単一モードの手順より前のものか、同等の vphoned による受け入れの証拠がないため、現在のサポート表ではなく研究の経緯として扱ってください。
+
+| ホスト | iPhone | CloudOS |
+| --------------- | --------------------- | --------------- |
+| Mac16,11 27.0b2 | `17,3_18.6.2_22G100` | `26.1-23B85` |
+| Mac16,8 26.5.1 | `17,3_26.0_23A341` | `26.1-23B85` |
+| Mac16,8 26.5.1 | `17,3_26.0.1_23A355` | `26.1-23B85` |
+| Mac16,12 26.3 | `17,3_26.1_23B85` | `26.1-23B85` |
+| Mac16,12 26.3 | `17,3_26.3_23D127` | `26.1-23B85` |
+| Mac16,12 26.3 | `17,3_26.3_23D127` | `26.3-23D128` |
+| Mac16,12 26.3 | `17,3_26.3.1_23D8133` | `26.3-23D128` |
+| Mac16,11 26.2 | `17,3_26.4_23E246` | `26.4-23E5207q` |
+| Mac16,11 26.2 | `17,3_26.5_23F77` | `26.4-23E5207q` |
+| Mac16,11 27.0b2 | `17,3_26.5.2_23F84` | `26.4-23E5207q` |
+| Mac16,6 26.4.1 | `17,3_26.6_23G71` | `26.4-23E5207q` |
+| Mac16,11 27.0b2 | `17,3_26.6.1_23G83` | `26.4-23E5207q` |
+| Mac16,6 26.6.1 | `17,3_26.6.2_23G90` | `26.4-23E5207q` |
+| Mac16,11 27.0b2 | `17,3_27.0_24A5380h` | `26.4-23E5207q` |
+| Mac16,6 26.4.1 | `17,3_27.0_24A5390f` | `26.4-23E5207q` |
+| Mac16,6 26.6.1 | `17,3_27.0_24A5408d` | `26.4-23E5207q` |
+| Mac16,11 27.0b2 | `17,3_27.0_24A5418b` | `26.4-23E5207q` |
+| Mac16,11 27.0b2 | `17,3_27.0_24A5424a` | `26.4-23E5207q` |
+| Mac16,11 27.0b2 | `17,3_27.0_24A5430a` | `26.4-23E5207q` |
+| Mac16,6 26.6.1 | `17,3_27.0_24A435` | `26.4-23E5207q` |
+
+すべてのパッチとその適用先の一覧は、[パッチ一覧](../../../Research/0_binary_patch_comparison.md)をご覧ください。
+
+## 関連項目
+
+- [ファームウェアの準備](firmware-preparation.md)
+- [その他の iPhone モデル](iphone-models.md)
+- [iPadOS ゲスト](ipados.md)
+- [マシンの作成と実行](../machines/create-and-run.md)
diff --git a/Documents/ja/firmware/firmware-preparation.md b/Documents/ja/firmware/firmware-preparation.md
new file mode 100644
index 00000000..17e7c76c
--- /dev/null
+++ b/Documents/ja/firmware/firmware-preparation.md
@@ -0,0 +1,71 @@
+# ファームウェアの準備
+
+ファームウェアにパッチを適用する前に `vm create` と `fw prepare` が 2 つの IPSW に対して行うこと、そして vphone600 のコンポーネントを含まない cloudOS で必要になる追加の手順を説明します。段階を手動で実行する場合、GPU ドライバを再利用する場合、研究用ボードの組み合わせでマシンを作成する場合にご覧ください。
+
+## GPU ドライバ
+
+`fw prepare` がハイブリッドな iPhone の復元イメージを作るには、cloudOS から準仮想化 GPU ドライバを取得する必要があります。取得は次の手順で行われます。
+
+1. ネットワークデバイスのない一時的な vphone 仮想マシンを作成し、DFU で起動します。
+2. vphone 独自の復元バックエンドで、選択した cloudOS の IPSW をその仮想マシンに復元します。
+3. 復元した System ボリュームを読み取り専用でマウントし、GPU バンドルを取り出します。
+4. 一時的な仮想マシンを削除します。
+
+取り出したバンドルは cloudOS のビルドごとに `~/.vphone/gpu-drivers/` にキャッシュされるため、同じ cloudOS で作成する以降のマシンでは一時的な復元が省かれます。
+
+以前に取り出したバンドルを再利用するには、`vm create` または `fw prepare` に渡します。
+
+```sh
+vphone-cli fw prepare myphone \
+ --gpu-driver-bundle /path/to/AppleParavirtGPUMetalIOGPUFamily.bundle
+```
+
+CLI はバンドルの iPhoneOS プラットフォームのバージョンを、選択した cloudOS のバージョンと照合します。各復元はそれぞれオンラインでチケットを取得します。
+
+バンドルには arm64e の GPU コンパイラプラグインも同梱されています。`fw prepare` は、パッチの適用とインストールの前に、それを準備した GPU バンドルにコピーします。
+
+## 研究用ボードの組み合わせ
+
+26.4 ベータより後の cloudOS には vphone600 のコンポーネントがないため、研究用ボードが代わりを務めます([互換性](compatibility.md)の「どの cloudOS を使うか」をご覧ください)。その kernelcache は、vphone600 の仮想化 kext を加えて作り直されます。KDK の展開はあなたのユーザ権限でネイティブに実行され、root が必要なのは kmutil によるリンクだけです。
+
+1. 通常どおり `fw prepare` を実行します。
+2. 自分のユーザ権限でミックスを準備します。
+
+ ```sh
+ vphone-cli fw kernelcache myphone
+ ```
+
+3. root としてリンクします。
+
+ ```sh
+ sudo vphone-cli fw kernelcache myphone
+ ```
+
+4. `fw patch` に進みます。`fw patch` はキャッシュからミックスを取得します。
+
+`fw kernelcache` の古い `--ipsw` 引数は引き続き受け付けられますが、無視されます。
+
+## 別の Mac でリンクする
+
+カーネルは Apple がリンクしたレイアウトでしか起動せず、kmutil はレイアウトを実行中の Mac から決めます。
+
+| ホストの macOS | リンクできるもの |
+| --- | --- |
+| macOS 26.4 以降 | iOS 26.4 以降の kernelcache(kernel-last) |
+| macOS 15、および 26.0〜26.3 | iOS 18 などの古い kernelcache(kernel-first) |
+
+この Mac のレイアウトが異なる場合は、別の Mac または macOS 仮想マシンが ssh 経由でミックスをリンクします。`fw kernelcache` または作成処理のために、次を設定します。
+
+```sh
+export VPHONE_KMUTIL_SSH='user@host'
+export VPHONE_KMUTIL_SSH_PASSWORD='password' # only without ssh keys and passwordless sudo there
+```
+
+準備したボリュームはその Mac の `/private/var/tmp` にアップロードされ、そこで root としてリンクされた後、削除されます。この Mac では root 権限は必要ありません。別の Mac ではリモートログインがオンになっていて、そのユーザが sudo を使えることが必要です。
+
+## 関連項目
+
+- [ファームウェアの互換性](compatibility.md)
+- [マシンの作成と実行](../machines/create-and-run.md)
+- [ライブラリ、ファームウェア、バックアップ](../storage/library-and-backups.md)
+- [kernelcache のレシピ](../../../VPhoneExecutable/VPhoneVirtualization/Resources/kernelcache_recipes/README.md)
diff --git a/Documents/ja/firmware/ipados.md b/Documents/ja/firmware/ipados.md
new file mode 100644
index 00000000..64db29cd
--- /dev/null
+++ b/Documents/ja/firmware/ipados.md
@@ -0,0 +1,96 @@
+# iPadOS ゲスト
+
+vphone のマシンで iOS の代わりに iPadOS を実行する方法です。iPad のユーザランド、画面サイズ、マルチタスク機能が必要な場合に使います。
+
+仮想ハードウェアは変わりません。ブートチェーン、カーネル、SEP、デバイスツリーは引き続き PCC の cloudOS IPSW(`vresearch101ap` / `vphone600ap`)から取得します。ユーザランドだけが iPhone17,3 ではなく iPad の復元用 IPSW から取得され、ユーザランドから iPad に見えるようにデバイスツリーが書き換えられます。
+
+![vphone の仮想マシンで表示した iPadOS のホーム画面](../../ipados-demo.jpeg)
+
+## 作成する
+
+### Launchpad で
+
+1. **New Machine** を選びます。
+2. **Device** で iPad を、**iPadOS** でリリースを選びます。推奨される cloudOS も一緒に選ばれます。
+3. カタログにない IPSW を使う場合は、**Source** を **Custom IPSWs** にし、**iPhone IPSW** 欄に iPad の IPSW を、もう一方の欄に cloudOS の IPSW を入力します。
+
+**Device** メニューは、カタログに iPad が含まれる Core Bundle の場合にだけ表示されます。ターミナルからは、`vphone-launchpad-cli vm create <name> --device iPad16,1` で同じことができます。
+
+### vphone-cli で
+
+iPhone の IPSW を渡す場所に、iPad の復元用 IPSW を渡します。cloudOS は、同じリリースの iPhone ゲストが使うものと同じです。
+
+```sh
+vphone-cli vm create ipad-mini \
+ --iphone-source 'https://updates.cdn-apple.com/2026SummerFCS/cf7db64d-5866-4bf2-bfff-50a32f58bec3/iPad16,1,iPad16,2_26.6.2_23G90_Restore.ipsw' \
+ --cloudos-source 'https://updates.cdn-apple.com/private-cloud-compute/c0ecdb4b310cf5239ab2b248dd3098eec297dc5aa3bbe6ada27273262b0b8b64'
+
+# The 13-inch iPad Pro (M5), from the IPSW that also carries the 11-inch
+vphone-cli vm create ipad-pro-13 --device iPad17,3 \
+ --iphone-source 'https://updates.cdn-apple.com/2026SummerFCS/<…>/iPad17,1,iPad17,2,iPad17,3,iPad17,4_26.6.2_23G90_Restore.ipsw' \
+ --cloudos-source 'https://updates.cdn-apple.com/private-cloud-compute/c0ecdb4b310cf5239ab2b248dd3098eec297dc5aa3bbe6ada27273262b0b8b64'
+```
+
+リリースを探すには:
+
+| コマンド | 表示されるもの |
+| --- | --- |
+| `vphone-cli fw catalog` | サポートされるすべての iPad の iPadOS リリースと、それぞれの cloudOS |
+| `vphone-cli fw catalog --device iPad16,1` | 1 台の iPad のリリース |
+| `vphone-cli fw prepare --device iPad16,1 --list` | その iPad でダウンロードできる IPSW |
+| `vphone-cli fw prepare --device iPad16,1 --iphone-version 26.6.2` | 1 つの IPSW を特定 |
+
+`--device` を指定してソースを指定しない場合、`vm create` はその iPad のリリースを選択肢として表示します。
+
+### 共有 IPSW でモデルを選ぶ
+
+ほとんどの iPad の IPSW は複数のモデルに対応しています。iPad Air と iPad Pro の IPSW には両方のサイズが含まれます。`--device` を指定しないと、`fw prepare` は IPSW に最初に記載されたモデル(11 インチ)を選びます。13 インチにするには、`fw prepare` または `vm create` に `--device iPad17,3` を渡します。Launchpad の New Machine は **Device** で選んだモデルを渡します。**Custom IPSWs** の場合は最初のモデルを選びます。
+
+<img src="../../ipados/ipad-pro-13-home.jpg" alt="vphone の仮想マシンで表示した 13 インチ iPad Pro のホーム画面" width="360" />
+
+### 手動の段階
+
+手動の段階は iPhone ゲストと同じです:`vm new`、`fw prepare`、`fw patch`、DFU と `restore`、`cfw install`、`vm launch`。iPad で動作が異なるのは `fw prepare` と `fw patch` だけで、DFU、`restore`、`cfw install` はそのまま実行されます。
+
+## サポートされるデバイス
+
+| 製品 | モデル | ボード | パネル | ポイント @2x |
+| --- | --- | --- | --- | --- |
+| `iPad16,1` | iPad mini(A17 Pro) | J410AP | 1488x2266 @ 326 ppi | 744x1133 |
+| `iPad15,7` | iPad(A16) | J481AP | 1640x2360 @ 264 ppi | 820x1180 |
+| `iPad15,3` | 11 インチ iPad Air(M3) | J607AP | 1640x2360 @ 264 ppi | 820x1180 |
+| `iPad15,5` | 13 インチ iPad Air(M3) | J637AP | 2048x2732 @ 264 ppi | 1024x1366 |
+| `iPad16,3` | 11 インチ iPad Pro(M4) | J717AP | 1668x2420 @ 264 ppi | 834x1210 |
+| `iPad16,5` | 13 インチ iPad Pro(M4) | J720AP | 2064x2752 @ 264 ppi | 1032x1376 |
+| `iPad17,1` | 11 インチ iPad Pro(M5) | J817AP | 1668x2420 @ 264 ppi | 834x1210 |
+| `iPad17,3` | 13 インチ iPad Pro(M5) | J820AP | 2064x2752 @ 264 ppi | 1032x1376 |
+
+セルラーモデル(`iPad16,2`、`iPad15,4`、`iPad15,6`、`iPad16,4`、`iPad16,6`、`iPad17,2`、`iPad17,4`)は、対応する Wi-Fi モデルと IPSW を共有し、そのモデルとして動作します。仮想マシンにはベースバンドがありません。`iPad15,8` は Wi-Fi モデルのボードを含まない独自の IPSW で配布されており、サポートされていません。
+
+テスト済みの組み合わせは[互換性](compatibility.md)にあります。
+
+## iPad で変わること
+
+- **`fw prepare`** は `SupportedProductTypes` から IPSW を認識し、ゲストのボードに対応する消去用アイデンティティと `DeviceMap` のエントリを選び(iPad の IPSW は複数のボードに対応しています)、製品タイプと iPad のディスプレイをマシンの `config.plist`(`guestProductType`、`screenConfig`)に記録します。復元ツリーの名前は `iPhoneOS_iPad16,1_<version>_<build>_Restore` になります。`iPhone` という接頭辞は、復元ツリーを読み取るすべての処理が照合する命名規則であり、デバイスを表すものではありません。
+- **2 つのデバイスツリー。** ハイブリッドなマニフェストでは、通常 `DeviceTree` と `RestoreDeviceTree` が同じ vphone600 のファイルを指します。iPad の場合、`DeviceTree` はコピーである `Firmware/all_flash/DeviceTree.vphone600ap.guest.im4p` を指します。復元時は、`restored_external` がマニフェストと照合する未変更のアイデンティティ(`iPhone99,11`)で起動し、ゲストはコピーで起動します。
+- **`fw patch`** は、そのコピーに iPad のアイデンティティと表示を与えます(パッチセット `devicetree`、エントリ `devicetree-cfw-ipad_*`)。
+ - ルートの `model`、`target-type`、`target-sub-type` をボードと同じ値にし(iPad mini の場合は `iPad16,1`、`J410`、`J410AP`)、`compatible` はボードを先頭にして `VPHONE600AP` を 2 番目に残します。
+ - `/product`:ボードのアートワークのイディオム、サブタイプ、スケール、製品名、外観、カメラとボタンの配置、マルチタスク機能(`medusa-overlay-app-capability`、`ui-floating-live-app`、`ui-overlay-app`、`ui-pinned-app`、そしてステージマネージャのないボードでは `disable-chamois`)、製品タイプと固有のモデル。これらはすべて、復元ツリーに残っているボードの `DeviceTree.<board>.im4p` から読み取ります。
+ - iPhone 専用の `syscfg` のプレースホルダ(Dynamic Island、簡易アクセス、着信/サイレントスイッチ、音量ボタンの配置、CarPlay、Apple Watch のペアリング)は削除されます。
+
+ 仮想ハードウェアは vphone600 の記述のままです:GPU の機能セット、フレームバッファ、メモリクラス、ブートフラグ。
+- **LLB** には、iPad ゲストの場合にもう 1 つのパッチ `llb-cfw-display_scale` が適用されます。LLB は準仮想化ディスプレイのブートビデオのワードから `/chosen/display-scale` を設定しますが、この値は常に 3x を示します。MobileGestalt はこのプロパティを画面のスケールとして使うため、iPad では 496x755 ポイントのキャンバスになってしまいます。このパッチで、LLB が iPad 本来のスケール(iPad mini の場合は 2x、744x1133 ポイント)を書き込むようにします。
+- **`cfw install`** は、インストールされたデバイスツリーに手を加えません。iPhone17,3 の復元後のアイデンティティ書き換え(`preboot-exp-devicetree_identity`)は、iPad ゲストでは省かれます。
+- **マシンのウィンドウ**は `screenConfig` に従うため、iPad の縦横比で開きます。
+
+<img src="../../ipados/display-scale-3x-before.jpg" alt="LLB パッチ適用前の、3x のディスプレイスケールで表示された iPad ゲスト" width="240" />
+
+## iPad を追加する
+
+iPad のモデルを追加するには、[`VPhoneGuestDevice`](../../../VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneGuestDevice.swift) に製品タイプ、ボード、パネルの 1 行を加えるだけです。デバイスツリーに必要な情報は、すべて IPSW 内のボード自身の `DeviceTree.<board>.im4p` から読み取られます。
+
+## 関連項目
+
+- [その他の iPhone モデル](iphone-models.md)
+- [ファームウェアの互換性](compatibility.md)
+- [マシンの作成と実行](../machines/create-and-run.md)
diff --git a/Documents/ja/firmware/iphone-models.md b/Documents/ja/firmware/iphone-models.md
new file mode 100644
index 00000000..71fc6672
--- /dev/null
+++ b/Documents/ja/firmware/iphone-models.md
@@ -0,0 +1,67 @@
+# その他の iPhone モデル
+
+iPhone17,3(iPhone 16)ではなく、別の iPhone の復元用 IPSW から取得した iOS でゲストを実行する方法です。特定のモデルのユーザランド、パネルサイズ、アイデンティティが必要な場合に使います。
+
+[iPad ゲスト](ipados.md)と同じく、仮想ハードウェアは変わりません。ブートチェーン、カーネル、SEP、デバイスツリーは引き続き PCC の cloudOS IPSW(`vresearch101ap` / `vphone600ap`)から取得します。ユーザランドだけが選んだモデルの IPSW から取得され、ゲストが起動に使うデバイスツリーはそのモデルとして見えるように書き換えられます。
+
+## 作成する
+
+Launchpad では、**New Machine** を選び、**Device** でモデルを、**iOS** でリリースを選びます。
+
+ターミナルから Launchpad を通じて作成する場合:
+
+```sh
+vphone-launchpad-cli vm create iphone17pro --device iPhone18,1
+```
+
+`vphone-cli` では、モデルの IPSW と cloudOS を渡します。
+
+```sh
+vphone-cli vm create iphone17pro \
+ --iphone-source 'https://updates.cdn-apple.com/2026SummerFCS/f768ecdf-e037-44e6-bfa6-949b6d127c4f/iPhone18,1_26.6.2_23G90_Restore.ipsw' \
+ --cloudos-source 'https://updates.cdn-apple.com/private-cloud-compute/c0ecdb4b310cf5239ab2b248dd3098eec297dc5aa3bbe6ada27273262b0b8b64'
+```
+
+iPhone の各モデルにはそれぞれ専用の IPSW があるため、ソースを明示する場合は `--device` は不要です。
+
+リリースを探すには `fw catalog` を実行します。iPhone 16 と 17 の各モデルの 26.0〜27.0.1 のリリース(iPhone 17e は 26.3.1 から)と iPhone 18 Pro の 27.0.1 が、同じリリースの iPhone17,3 が使う cloudOS とともに表示されます。1 つのモデルのリリースを表示するには:
+
+```sh
+vphone-cli fw catalog --device iPhone18,1
+```
+
+## サポートされるデバイス
+
+| 製品 | モデル | ボード | パネル | ポイント @3x |
+| --- | --- | --- | --- | --- |
+| `iPhone17,3` | iPhone 16 | D47AP | 1290x2796 @ 460 ppi | 430x932 |
+| `iPhone17,4` | iPhone 16 Plus | D48AP | 1290x2796 @ 460 ppi | 430x932 |
+| `iPhone17,1` | iPhone 16 Pro | D93AP | 1206x2622 @ 460 ppi | 402x874 |
+| `iPhone17,2` | iPhone 16 Pro Max | D94AP | 1320x2868 @ 460 ppi | 440x956 |
+| `iPhone17,5` | iPhone 16e | V59AP | 1170x2532 @ 460 ppi | 390x844 |
+| `iPhone18,3` | iPhone 17 | V57AP | 1206x2622 @ 460 ppi | 402x874 |
+| `iPhone18,4` | iPhone Air | D23AP | 1260x2736 @ 460 ppi | 420x912 |
+| `iPhone18,1` | iPhone 17 Pro | V53AP | 1206x2622 @ 460 ppi | 402x874 |
+| `iPhone18,2` | iPhone 17 Pro Max | V54AP | 1320x2868 @ 460 ppi | 440x956 |
+| `iPhone18,5` | iPhone 17e | V159AP | 1170x2532 @ 460 ppi | 390x844 |
+| `iPhone19,2` | iPhone 18 Pro | V63AP | 1206x2622 @ 460 ppi | 402x874 |
+
+iPhone17,3 を含むすべてのモデルが、パネルとアイデンティティを自身のデバイスツリーから取得します。iPhone17,3 のパネルは、これまでと同じディスプレイです。
+
+iPhone 17 Pro、17 Pro Max、18 Pro には起動検証の記録があります。[互換性](compatibility.md)の「その他の iPhone モデル」をご覧ください。iPhone 17 Pro と 17 Pro Max は iOS 27 でパッチが必要で、その内容も同じ箇所に記載されています。
+
+> [!WARNING]
+> iPhone19,2 は ARM64E_X1 を使います。X1 にネイティブ対応していないホストでは、standard プリセットがサポートされていない命令を置き換えるため、PC に結び付いたポインタ認証が弱まります。
+
+## 別の iPhone で変わること
+
+[iPadOS ゲスト](ipados.md)の「iPad で変わること」に記載された内容がすべて当てはまりますが、違いが 2 つあります。
+
+- ボードの `/product` の値が同じ方法で vphone600 のプレースホルダを置き換えますが、iPhone のボードでは iPhone 固有のプロパティが残ります。Dynamic Island、簡易アクセス、OLED、音量ボタンの配置、CarPlay、Apple Watch のペアリングは、削除されずにボードから取得されます。パッチ ID は `devicetree-cfw-ipad_*` のままです。これらは iPhone で使われるようになる前に名付けられました。
+- LLB にディスプレイスケールのパッチは適用されません。準仮想化ディスプレイのブートビデオのワードは 3x を示しており、これはもともと iPhone のスケールです。
+
+## 関連項目
+
+- [iPadOS ゲスト](ipados.md)
+- [ファームウェアの互換性](compatibility.md)
+- [マシンの作成と実行](../machines/create-and-run.md)
diff --git a/Documents/ja/get-started/downloads.md b/Documents/ja/get-started/downloads.md
new file mode 100644
index 00000000..0ceca726
--- /dev/null
+++ b/Documents/ja/get-started/downloads.md
@@ -0,0 +1,86 @@
+# ダウンロード
+
+ダウンロードする Launchpad のバージョンと、それに対応する `VPhone.bundle` を選びます。最新のリリースに公証済みの Launchpad がない場合や、バージョンを手動で合わせる必要がある場合にこのページを使います。
+
+## 各リリースの内容
+
+各[リリース](https://github.com/Lakr233/vphone-cli/releases)には最大 3 つのファイルがあります。
+
+| ファイル | 内容 |
+| --- | --- |
+| `vphone-launchpad-<version>-notarized.zip` | Apple による署名と公証を受けた Launchpad です。ある場合はこちらをダウンロードしてください。 |
+| `vphone-launchpad-<version>.zip` | 公証されていない Launchpad です。初めて開くときに macOS にブロックされます。 |
+| `VPhone-<version>.zip` | `VPhone.bundle` です。Launchpad が自動でダウンロードしてインストールするため、このファイルは不要です。 |
+
+公証されていないバージョンを開くには、一度開いてから **システム設定 > プライバシーとセキュリティ** に移動し、**このまま開く** をクリックします。
+
+## 公証済みの Launchpad バージョン
+
+| シリーズ | 公証済み | 未公証 |
+| --- | --- | --- |
+| 2.15 | 2.15.0 | 2.15.1 |
+| 2.14 | 2.14.0 | 2.14.1, 2.14.2 |
+| 2.13 | 2.13.0 | 2.13.1, 2.13.2, 2.13.3, 2.13.4, 2.13.5, 2.13.6, 2.13.7, 2.13.8 |
+| 2.12 | 2.12.0, 2.12.2 | 2.12.1 |
+| 2.11 | 2.11.0 | — |
+| 2.10 | 2.10.1 | — |
+| 2.9 | 2.9.0, 2.9.1, 2.9.2 | 2.9.3, 2.9.4, 2.9.5 |
+| 2.8 | 2.8.0 | — |
+| 2.7 | 2.7.0 | — |
+| 2.6 | 2.6.0 | 2.6.1 |
+| 2.5 | 2.5.0 | 2.5.1 |
+| 2.4 | 2.4.0, 2.4.1 | 2.4.2 |
+| 2.3 | 2.3.0 | 2.3.1, 2.3.2 |
+| 2.2 | 2.2.0, 2.2.2, 2.2.3, 2.2.4, 2.2.5 | 2.2.1 |
+| 2.1 | 2.1.0, 2.1.1, 2.1.2 | 2.1.3, 2.1.4, 2.1.5, 2.1.6, 2.1.7 |
+| 2.0 | 2.0.4, 2.0.5, 2.0.6, 2.0.8, 2.0.9 | — |
+
+2.0.7 と 2.10.0 のリリースはありません。
+
+## Launchpad と VPhone.bundle の対応
+
+Launchpad と同じシリーズの `VPhone.bundle` を使います。シリーズとはバージョンの最初の 2 つの数字のことです。Launchpad 2.2.3 は 2.2 シリーズに属し、どの `VPhone.bundle` 2.2.x とも動作します。
+
+| Launchpad | VPhone.bundle |
+| --- | --- |
+| 2.15.x | 2.15.x |
+| 2.14.x | 2.14.x |
+| 2.13.x | 2.13.x |
+| 2.12.x | 2.12.x |
+| 2.11.x | 2.11.x |
+| 2.10.x | 2.10.x |
+| 2.9.x | 2.9.x |
+| 2.8.x | 2.8.x |
+| 2.7.x | 2.7.x |
+| 2.6.x | 2.6.x |
+| 2.5.x | 2.5.x |
+| 2.4.x | 2.4.x |
+| 2.3.x | 2.3.x |
+| 2.2.x | 2.2.x |
+| 2.1.x | 2.1.x |
+| 2.0.x | 2.0.x |
+
+同じシリーズの中では、最新の `VPhone.bundle` をインストールしてください。パッチリリースは、Launchpad とバンドルの連携方法を変えずに問題を修正するものです。
+
+Launchpad は古すぎる `VPhone.bundle` を拒否しますが、新しいシリーズのバンドルを一覧に表示することはあります。それらはインストールせず、先に Launchpad をそのシリーズに更新してください。
+
+> [!NOTE]
+> Launchpad は自動では更新されません。リリースページから新しいバージョンをダウンロードし、古いアプリと置き換えてください。
+
+## 最近のシリーズで追加されたもの
+
+| シリーズ | 追加 | 備考 |
+| --- | --- | --- |
+| 2.15 | HomeView | New Machine が `HomeAccessory17,1` と `HomeAccessory17,2` に `homeview` プリセットを選ぶよう、Launchpad 2.15 は同じシリーズのバンドルと組み合わせて使います。 |
+| 2.14 | ファイルからのパッチプリセット:プリセットの選択メニューの **Other…**、または `--preset <path>` | Launchpad 2.14 には 2.14 のバンドルが必要です。 |
+| 2.13 | Apple TV 4K(第 4 世代) | New Machine が `AppleTV18,1` に `tvos-4k` プリセットを選ぶよう、Launchpad 2.13 は同じシリーズのバンドルと組み合わせて使います。 |
+
+## バージョン 1.x
+
+1.x で作成した仮想マシンは 2.x では起動しません。1.x については [1.0.14 リリース](https://github.com/Lakr233/vphone-cli/releases/tag/1.0.14)をご覧ください。
+
+## 関連項目
+
+- [クイックスタート](quick-start.md)
+- [Core Bundle](../launchpad/core-bundles.md)
+- [Launchpad コマンドライン](../launchpad/launchpad-cli.md)
diff --git a/Documents/ja/get-started/host-setup.md b/Documents/ja/get-started/host-setup.md
new file mode 100644
index 00000000..512915d0
--- /dev/null
+++ b/Documents/ja/get-started/host-setup.md
@@ -0,0 +1,112 @@
+# ホストの設定
+
+エンタイトルメント付きの仮想マシンプロセス `vphone-vm` を実行できるように Mac を準備します。この作業は Mac ごとに 1 回行います。許可リストの手順は、`vphone-vm` の署名が変わるたびに繰り返します。
+
+macOS 15 以降を搭載した Apple Silicon Mac が必要です。PV=3 の研究用ゲストは、入れ子にした macOS 仮想マシンの中では動作しません。
+
+## ホストを確認する
+
+使用する `VPhone.bundle` の事前チェックを実行します。
+
+```sh
+vphone-cli host preflight
+```
+
+仮想マシンを起動する前に、エンタイトルメント付きの `vphone-vm` をチェックします。AMFI が `vphone-vm` を拒否した場合は、そのバンドル用の `sudo .../vphone-escalator allow .../vphone-vm` コマンドがそのままエラーに表示されます。
+
+## セキュリティ構成を選ぶ
+
+`vphone-vm` は Apple の非公開の仮想化エンタイトルメントを持つため、macOS がそれを受け入れる必要があります。次の 2 つのオプションのどちらでも、macOS 復旧で Research Guests を有効にする必要があります。どちらか 1 つを選んでください。
+
+### オプション A:SIP を有効にしたままデバッグの制限を緩和する
+
+1. macOS 復旧で起動してターミナルを開き、次のコマンドを実行します。
+
+ ```sh
+ csrutil enable --without debug
+ csrutil allow-research-guests enable
+ ```
+
+2. macOS で再起動します。
+3. 現在の `vphone-vm` を許可リストに追加します。配布されたバンドルの場合は、`vphone-cli host preflight` を実行し、表示されたコマンドを実行します。ソースのチェックアウトからの場合:
+
+ ```sh
+ bundle=.build/XcodeBundle/Build/Products/Debug/VPhone.bundle
+ sudo "$bundle/Contents/MacOS/vphone-escalator" allow "$bundle/Contents/MacOS/vphone-vm"
+ "$bundle/Contents/MacOS/vphone-escalator" status
+ "$bundle/Contents/MacOS/vphone-cli" host preflight
+ ```
+
+> [!WARNING]
+> `allow` コマンドは、署名だけが変わる再ビルドも含め、ビルドのたびに実行し直してください。許可リストには `vphone-vm` の cdhash が登録されており、署名が変わると cdhash も変わります。
+
+許可リストを元に戻すには:
+
+```sh
+sudo "$bundle/Contents/MacOS/vphone-escalator" off
+```
+
+`off` は `vphone-escalator` が追加したハッシュだけを削除し、amfid を再起動します。環境設定そのものとその他の値はそのまま残ります。
+
+制限付きのエンタイトルメントが必要な署名済みのホスト用バイナリがほかにもある場合は、同じ `allow` コマンドにまとめて渡せます。エンタイトルメントを持たない `vphone-cli` には不要です。
+
+### オプション B:SIP と AMFI を無効にする
+
+制限がより緩い構成です。
+
+1. macOS 復旧で起動してターミナルを開き、次のコマンドを実行します。
+
+ ```sh
+ csrutil disable
+ csrutil allow-research-guests enable
+ ```
+
+2. macOS で再起動し、ブート引数を設定して、もう一度再起動します。
+
+ ```sh
+ sudo nvram boot-args="amfi_get_out_of_my_way=1 -v"
+ ```
+
+> [!WARNING]
+> このコマンドは既存の `boot-args` を置き換えます。先に `nvram boot-args` で確認してください。
+
+## Launchpad を使う場合
+
+Launchpad のバンドル事前チェックは、SIP のデバッグ制限が無効になっているか(または SIP 全体が無効か)、Research Guests が有効かを確認します。`vphone-escalator` を自分で実行する必要はありません。
+
+- インストールされた `vphone-vm` を AMFI がブロックした場合、Launchpad のヘルパーがそれらのホスト設定を再確認し、root 所有のバンドルとその記録済みの cdhash を検証してから、そのバンドルの `vphone-escalator allow` を root として実行します。その後 Launchpad が事前チェックをやり直します。
+- バンドルの新しい署名は、それぞれ個別にチェックされ許可されます。
+- 新しい Launchpad に新しいヘルパーが含まれている場合は、起動時にヘルパーを更新するための管理者の認証を求めます。
+
+単体の `vphone-cli` では、引き続き手動で実行するコマンドが表示されます。
+
+## ソースからビルドする
+
+配布される `VPhone.bundle` は、実行時に Homebrew、Python、Xcode を必要としません。ソースからビルドするには、Xcode と、`vphoned` をコンパイルするための iPhoneOS SDK が必要です。チェックアウトしたディレクトリで次を実行します。
+
+```sh
+xcodebuild -workspace VPhone.xcworkspace -scheme VPhone \
+ -configuration Debug -destination 'platform=macOS,arch=arm64' \
+ -derivedDataPath .build/XcodeBundle build
+.build/XcodeBundle/Build/Products/Debug/VPhone.bundle/Contents/MacOS/vphone-cli host preflight
+```
+
+`VPhone` スキームは、すべてのプログラムを含むアドホック署名のバンドルを生成します。オプション A を選んだ場合は、新しくビルドするたびに許可リストに追加してください。
+
+## 許可リストが変更する内容
+
+`vphone-escalator allow` は、AMFI のコード要件の環境設定がなければ作成します。すでにある場合は、その `Entitlements` 要件に現在の `vphone-vm` の cdhash を追加します。ほかの cdhash や環境設定のキーは残し、登録済みのハッシュは追加しません。既存の `AllowUnsafeDynamicLinking` の値には触れず、このキーがない場合にだけ `false` を書き込みます。amfid のヒープの 1 バイトを変更することで、amfid がこの要件を参照するようにします。
+
+## バンドルの中身
+
+- `vphone-cli` は非公開のエンタイトルメントなしで処理全体を取りまとめ、`vphone-cli archive` でアーカイブを扱います。
+- `vphone-vm` は署名済みでエンタイトルメントを持つ、仮想マシンとウィンドウのプロセスです。
+- `vphoned` はビルド時に iOS 向けにコンパイルされ、作成した各ゲストにインストールされます。
+
+実装の経緯については、[バイナリ分割に関する研究記録](../../../Research/Host/host_binary_split.md)をご覧ください。
+
+## 関連項目
+
+- [クイックスタート](quick-start.md)
+- [仮想マシンの作成と実行](../machines/create-and-run.md)
+- [トラブルシューティング](../help/troubleshooting.md)
diff --git a/Documents/ja/get-started/overview.md b/Documents/ja/get-started/overview.md
new file mode 100644
index 00000000..22c39c68
--- /dev/null
+++ b/Documents/ja/get-started/overview.md
@@ -0,0 +1,50 @@
+# 概要
+
+vphone-cli は Apple Silicon Mac で仮想 iPhone を実行します。このページでは、vphone-cli でできること、Mac に必要なもの、各プログラムの役割を説明します。
+
+> [!WARNING]
+> 本プロジェクトは、暗号資産やトークンを発行したことも、その発行を許可したこともありません。また、暗号資産による支払いや寄付は受け付けていません。本プロジェクトの名をかたって発行・宣伝されるものや、本プロジェクトとの関係をうたう暗号資産・トークンは、すべて詐欺です。
+
+![macOS 上で動作する仮想 iPhone](../../demo.jpeg)
+
+vphone-cli は Apple の Virtualization.framework と PCC 研究用仮想マシンを使って iOS を実行します。セキュリティ研究、リバースエンジニアリング、デバッグのためのツールです。
+
+## 機能
+
+- **グラフィカルウィンドウ:** Mac 上で仮想 iPhone の画面を操作し、アプリとファイルを閲覧し、スクリーンショットの撮影や画面収録ができます。
+- **カスタムファームウェア:** システムにはあらかじめパッチが適用されており、[パッケージ環境](../machines/package-environment.md)をインストールできます。
+- **バックアップと複製:** 仮想マシンの書き出し、読み込み、複製ができます。
+- **自動化 API:** 任意で有効にできる、ローカルの HTTP と WebSocket のインターフェースです。[自動化 API](../machines/automation-api.md) をご覧ください。
+- **追加の依存なし:** 実行時に Xcode、Python、Homebrew は不要です。
+
+## 必要なもの
+
+- macOS 15 以降を搭載した物理 Apple Silicon Mac。macOS の仮想マシン上では動作しません。
+- 空きディスク容量。仮想マシンごとに標準で 64 GB の仮想ディスクを使い、ファームウェアにも別途容量が必要です。
+- ネットワーク接続。システムの復元時に署名チケットをオンラインで取得します。
+- セキュリティ設定の変更。macOS 復旧で起動し、ターミナルで次のコマンドを実行してから再起動します。
+
+ ```sh
+ csrutil enable --without debug
+ csrutil allow-research-guests enable
+ ```
+
+ SIP は有効のまま、デバッグの制限だけを緩和します。詳しくは[ホストの設定](host-setup.md)をご覧ください。
+
+## 4 つのプログラム
+
+| プログラム | 役割 |
+| --- | --- |
+| `vphone-launchpad` | `VPhone.bundle` のダウンロードとインストール、ホストの設定を行う Mac アプリです。別途配布されます。 |
+| `vphone-cli` | ファームウェアの準備、パッチの適用、システムの復元、仮想マシンの管理を行います。 |
+| `vphone-vm` | 仮想マシンを実行し、そのウィンドウを表示します。 |
+| `vphoned` | 仮想マシン内の制御サービスです。ウィンドウの機能と API はこれを通じて動作します。 |
+
+`vphone-cli`、`vphone-vm`、`vphoned` は `VPhone.bundle` にまとめて同梱されています。Launchpad はこのバンドル内の `vphone-cli` を使って各仮想マシンを操作します。ターミナルから `vphone-cli` を直接実行することもできます。
+
+## 関連項目
+
+- [クイックスタート](quick-start.md)
+- [ホストの設定](host-setup.md)
+- [ダウンロード](downloads.md)
+- [仮想マシンの作成と実行](../machines/create-and-run.md)
diff --git a/Documents/ja/get-started/quick-start.md b/Documents/ja/get-started/quick-start.md
new file mode 100644
index 00000000..414e4ec4
--- /dev/null
+++ b/Documents/ja/get-started/quick-start.md
@@ -0,0 +1,42 @@
+# クイックスタート
+
+Launchpad で vphone をセットアップし、最初の仮想 iPhone を起動します。Mac が[概要](overview.md)の「必要なもの」に記載された条件を満たしたら始めてください。
+
+## Launchpad でセットアップする
+
+1. [最新のリリース](https://github.com/Lakr233/vphone-cli/releases/latest)から `vphone-launchpad-<version>-notarized.zip` をダウンロードし、展開して開きます。すべてのリリースが公証済みとは限りません。最新のリリースに `-notarized` ファイルがない場合は、[ダウンロード](downloads.md)から公証済みのバージョンを選んでください。
+2. **Host Setup**(ホストの設定)でデベロッパツールへのアクセスを許可し、ヘルパーをインストールします。
+3. **Core Bundle** で **Download and Install**(ダウンロードしてインストール)をクリックします。
+4. **Machines**(マシン)で **New Machine**(新規マシン)をクリックし、ファームウェアの組み合わせを選んで **Create**(作成)をクリックします。
+
+Launchpad がファームウェアのダウンロード、パッチの適用、システムの復元、仮想マシンの起動を行います。自分で用意した iPhone と cloudOS の IPSW を使う場合は、[互換性](../firmware/compatibility.md)をご覧ください。
+
+## エージェントに任せる
+
+この Mac でコーディングエージェント(Claude Code、Codex など)を使っている場合は、手順を手作業で進める代わりに、次のプロンプトを貼り付けてください。エージェントは vphone スキルを読み、設定済みの部分を確認して Launchpad と `VPhone.bundle` をインストールします。管理者パスワードや macOS 復旧での変更など、あなたの操作が必要な手順では止まって確認します。
+
+```text
+この Mac に vphone をセットアップしてください。次のスキルを読み、
+https://raw.githubusercontent.com/Lakr233/vphone-cli/main/Skills/vphone-guest-control/SKILL.md
+そこからリンクされている references/ 以下(同じフォルダ)のファイルも読んで、その手順に従ってください:
+公証済みの最新の vphone-launchpad をインストールし(すべてのリリースに
+-notarized zip があるわけではありません)、vphone-launchpad-cli を PATH に通し、
+Launchpad と同じシリーズの VPhone.bundle をインストールして、
+`vphone-launchpad-cli status` で確認してください。SIP、boot-args などホストの
+セキュリティ設定は変更せず、ファームウェアと空きディスク容量を私が確認するまで
+マシンは作成しないでください。私の操作が必要な手順では、何をすればよいかを
+正確に伝えて待ってください。
+```
+
+## 次のステップ
+
+- 仮想マシンにパッケージマネージャをインストールする:[パッケージ環境](../machines/package-environment.md)
+- ターミナルから仮想マシンを操作する、または Launchpad を使わずに作成する:[仮想マシンの作成と実行](../machines/create-and-run.md)
+- HTTP と WebSocket で仮想マシンをスクリプトから操作する:[自動化 API](../machines/automation-api.md)
+- 問題が起きた場合:[トラブルシューティング](../help/troubleshooting.md)
+
+## 関連項目
+
+- [ホストの設定](host-setup.md)
+- [ダウンロード](downloads.md)
+- [Launchpad コマンドライン](../launchpad/launchpad-cli.md)
diff --git a/Documents/ja/help/troubleshooting.md b/Documents/ja/help/troubleshooting.md
new file mode 100644
index 00000000..1267e982
--- /dev/null
+++ b/Documents/ja/help/troubleshooting.md
@@ -0,0 +1,52 @@
+# トラブルシューティング
+
+表示されている症状やエラーメッセージを探し、その下の対処方法に従ってください。ネットワークの問題については[ネットワーク](../networking/overview.md)をご覧ください。
+
+## 仮想マシンが開く前に `vphone-vm` が強制終了される
+
+1. ホストの事前チェックを実行します。
+
+ ```sh
+ vphone-cli host preflight
+ ```
+
+ CLI はエンタイトルメントを持たないため強制終了されずに動作を続け、署名された `vphone-vm` を AMFI が拒否した理由を説明できます。
+2. バンドルをビルドし直した場合は、cdhash が変わっています。[ホストの設定](../get-started/host-setup.md)の説明に従い、同梱のヘルパーで新しいバイナリを許可してください。
+
+## `Virtualization is not available on this hardware`
+
+PV=3 のゲストは入れ子にできません。別の macOS 仮想マシンの中ではなく、Apple Silicon Mac で直接起動してください。
+
+## `vm create` が vphoned の成功を表示したのに、仮想マシンが実行されていない
+
+これは想定どおりの動作です。作成処理は一時的に GUI で起動し、実際に ping を送って、終了する前にその起動を停止します。使用するには仮想マシンを起動してください。
+
+```sh
+vphone-cli vm launch <name>
+```
+
+## 「Press home to continue」で止まる
+
+仮想マシンのウィンドウのタイトルバーにあるホームボタンをクリックします。現在の JB の手順では VNC サーバはインストールされません。
+
+## アプリが `EXC_GUARD` / `GUARD_TYPE_MACH_PORT` で終了する
+
+カーネルパッチ `kernel-boot-thread_guard_violation` は、致命的な Mach ポートガードの通知を止めます。このパッチは起動に必要な iOS 18 ベースでのみ適用され、そこではすべてのプリセットでオンになっています。ほかのベースでは選択できないため、26.x ベースでこのガードに引っかかるアプリは引き続き終了します。[issue #291](https://github.com/Lakr233/vphone-cli/issues/291) をご覧ください。
+
+## 復元または初回起動に失敗する
+
+- 手動の手順では、`restore` が終了するまで仮想マシンを DFU のままにしてください。
+- オンラインのチケット要求が Apple に届くことを確認してください。
+- 処理全体をやり直す場合は、**新しい名前**で、ツールの詳細を表示する `-v` を付けて `vm create` を再実行してください。
+- メモリやディスクに余裕がない場合は、仮想マシンを並行して作成しないでください。
+- iPhone の IPSW と PCC イメージを組み合わせる前に、[ファームウェアの互換性](../firmware/compatibility.md)を確認してください。
+
+## ゲストは起動するが、作成中に vphoned が応答しない
+
+初回起動のチェックは 300 秒でタイムアウトします。復元したばかりのゲストは、最初のヘッドレス起動で vphoned を立ち上げないことがあるため、作成処理では GUI で起動します。成功の表示が何を示すかについては、[作成と実行](../machines/create-and-run.md)をご覧ください。
+
+## 関連項目
+
+- [ホストの設定](../get-started/host-setup.md)
+- [作成と実行](../machines/create-and-run.md)
+- [ファームウェアの互換性](../firmware/compatibility.md)
diff --git a/Documents/ja/launchpad/bundle-integration.md b/Documents/ja/launchpad/bundle-integration.md
new file mode 100644
index 00000000..7b5e25f0
--- /dev/null
+++ b/Documents/ja/launchpad/bundle-integration.md
@@ -0,0 +1,59 @@
+# VPhone バンドルの組み込み
+
+このページは、`vphone-launchpad` のように `VPhone.bundle` を同梱したり操作したりするアプリケーションを作る人向けです。バンドルの中身と、組み込む側のアプリケーションが担う責任について説明します。
+
+## ビルドと検証
+
+```sh
+xcodebuild -workspace VPhone.xcworkspace -scheme VPhone \
+ -configuration Debug -destination 'platform=macOS,arch=arm64' \
+ -derivedDataPath .build/XcodeBundle build
+```
+
+`VPhone` スキームが `VPhone.bundle` を生成し、ビルドの一部として `ValidateBundle.sh` がそれをチェックします。
+
+## 組み込み方
+
+- バンドルはそのままの形で保ち、`Contents/MacOS/vphone-cli` をプロセスとして起動します。バンドルは実行ファイルとリソースのコンテナであり、macOS のアプリでも動的に読み込むプラグインでもありません。CLI は、自身の実行ファイルのパスを解決して、対になる `vphone-vm` を見つけます。
+- バンドル全体を、バージョン付きの 1 つの単位としてインストールし更新します。署名済みのバイナリをその場で書き換えないでください。
+- `vphone-vm` が変わると cdhash も変わります。新しいビルドを起動する前に、AMFI での許可を手配してください。
+- ダウンロード、リリースの検証、ホストでの実行許可、インストールと更新のポリシーは、組み込む側のアプリケーションが担います。デベロッパツールへのアクセスと AMFI の許可は、それぞれ別のホスト側の判断です。
+- 仮想マシンのライブラリとキャッシュは `VPhone.bundle` の外、標準では `~/.vphone` に置かれます。ホスト側の仮想マシンの出力はモード `0777` を使うため、root で実行した作成処理の後でも、別のワークステーションプロセスからアクセスできます。`Disk.img` 内のゲストのファイルシステムのアクセス権は、独自の意味を保ちます。
+
+## バンドルの中身
+
+| パス | 役割 |
+| --- | --- |
+| `Contents/MacOS/vphone-cli` | エンタイトルメントを持たないコマンドのエントリポイント |
+| `Contents/MacOS/vphone-vm` | 仮想マシンとウィンドウのプロセス。非公開の仮想化エンタイトルメントを持ちます |
+| `Contents/MacOS/vphone-escalator` | 現在の仮想マシンの cdhash 用の AMFI 許可リストツール |
+| `Contents/MacOS/libswiftCompatibilitySpan.vphone.dylib` | macOS 15 上の `vphone-vm` 用の Swift バックデプロイライブラリ |
+| `Contents/Resources/guest-resources/vphoned` | 独自のエンタイトルメントを持つ署名済みのゲストデーモン。バンドルに未署名のコピーは含まれません |
+| `Contents/Resources/guest-resources/*.dylib` | ゲストライブラリ:launchd フック、SystemHook、カメラフック、GPU コンパイラプラグイン、[`VPhoneGuestComponents`](../../../VPhoneGuestComponents/README.md) に記載された修正とデバイスアダプタ |
+| `Contents/Resources/guest-resources/*.plist` | ゲストの launch daemon の構成、カメラフックと MISFix のフィルタ |
+| `Contents/Resources` | ローカライズされた文字列。署名スクリプトやエンタイトルメントファイルは同梱されません |
+
+`Contents/MacOS` には Mac 上で動作するプログラムだけが入ります。`guest-resources` にはゲストにインストールされるファイルだけが入り、その中の Mach-O はすべて iOS 向けにビルドされています。`ValidateBundle.sh` がこの 2 つの規則を強制します。
+
+## 署名
+
+実行可能なペイロードはすべてアドホックのコード署名を使います。非公開のエンタイトルメントを持つのは、それを必要とする子プロセスだけです。バンドルには `CFBundleExecutable`、アプリランチャー、SMJobBless ヘルパー、インストーラ、パスワード入力、自動的な root 権限の取得のいずれもありません。
+
+## プライバシーの許可
+
+macOS は、責任プロセスに代わってプライバシーの許可(マイク、位置情報)を求め、その許可をプロセスのコード署名に紐付けます。
+
+- 責任を放棄した状態で `vphone-cli` を起動すると、`vphone-cli` が `vphone-vm` の責任プロセスになります。`vphone-cli` はアドホック署名なので、バンドルを新しくビルドするたびに再び許可を求められます。
+- 署名が変わらないプロセスの通常の子プロセスとして、責任を放棄せずに `vphone-cli` を起動すると、許可を求められるのは一度だけです。
+
+Launchpad は、自身の `Contents/MacOS` に含まれる `vphone-launchpad-launcher` を使って後者の方法を取っています。macOS はそこにあるツールを、それを含むアプリに帰属させるため、許可の確認、利用目的の説明、許可はそのアプリのものになります。Hardened Runtime では、アプリのメイン実行ファイルが対応するリソースエンタイトルメント(`com.apple.security.device.audio-input`、`com.apple.security.personal-information.location`)を持っている必要があります。持っていない場合、macOS は確認せずに要求を拒否します。
+
+## バージョンの互換性
+
+Launchpad は、`minimumBundleComponents`([`VPhoneLaunchpad/VPhoneLaunchpadShared/VPhoneLaunchpadBundleStore.swift`](../../../VPhoneLaunchpad/VPhoneLaunchpadShared/VPhoneLaunchpadBundleStore.swift) で設定)より古いバンドルを拒否し、古いバンドルのレイアウトは読み込みません。バンドル 2.1.0 で、パッチプリセット(`fw patches`、`fw set-patches`、`fw patch --preset`)と `vphone-escalator` 実行ファイルが追加されました。
+
+## 関連項目
+
+- [Core Bundle とローカルビルド](core-bundles.md)
+- [Launchpad コマンドライン](launchpad-cli.md)
+- [ホストの設定](../get-started/host-setup.md)
diff --git a/Documents/ja/launchpad/core-bundles.md b/Documents/ja/launchpad/core-bundles.md
new file mode 100644
index 00000000..df65ed7a
--- /dev/null
+++ b/Documents/ja/launchpad/core-bundles.md
@@ -0,0 +1,104 @@
+# Core Bundle とローカルビルド
+
+Launchpad の各マシンは、インストールされた 1 つの `VPhone.bundle` のバージョン、つまりその Core Bundle で動作します。このページでは、ローカルビルドをインストールする方法、マシンをそのビルドに移す方法、2 つのビルドを並べて比較する方法を説明します。
+
+## VPhone.bundle のビルドをテストする
+
+1. リポジトリのルートでバンドルをビルドします。
+
+ ```sh
+ xcodebuild -workspace VPhone.xcworkspace -scheme VPhone \
+ -configuration Debug -destination 'platform=macOS,arch=arm64' \
+ -derivedDataPath .build/XcodeBundle build
+ ```
+
+2. インストールします。バンドルは `<version>-local.<hash>` としてインストールされて標準のバンドルになり、実行ポリシーの例外が追加され、新しい `vphone-vm` の cdhash が許可され、ホストの事前チェックが実行されます。
+
+ ```sh
+ vphone-launchpad-cli bundle install-local .build/XcodeBundle/Build/Products/Debug/VPhone.bundle
+ ```
+
+ 正確なバージョンは、インストールの結果と `bundle list` に表示されます。
+
+3. 既存のマシンをそのバンドルに移します。`--update-environment` は新しい vphoned とフック用の dylib も配置し直すため、マシンを停止しておく必要があります。
+
+ ```sh
+ vphone-launchpad-cli vm set-bundle research-01 2.4.0-local.1a2b3c4d --update-environment
+ ```
+
+4. マシンを起動して確認します。
+
+ ```sh
+ vphone-launchpad-cli vm start research-01 --wait
+ vphone-launchpad-cli guest rpc research-01 device.info
+ vphone-launchpad-cli guest rpc research-01 apps.list '{}'
+ vphone-launchpad-cli vm log research-01 --lines 100
+ vphone-launchpad-cli vm stop research-01
+ ```
+
+ヘルパーの認証は 5 分間有効です。期限が切れた後、ヘルパーを必要とする最初の手順では、ウィンドウで操作した場合と同じく、Mac で管理者パスワードを求められます。
+
+既存の仮想マシンで永続シェーダキャッシュを有効にするための、1 回限りのカーネルとゲストの更新については、[永続シェーダキャッシュ](../storage/shader-cache.md)をご覧ください。
+
+## 2 つのビルドを比較する
+
+標準のバンドルを変えずに両方をインストールし、それぞれに専用のマシンを用意します。
+
+```sh
+vphone-launchpad-cli bundle install-local /path/to/A/VPhone.bundle --keep-default
+vphone-launchpad-cli bundle install-local /path/to/B/VPhone.bundle --keep-default
+vphone-launchpad-cli bundle list # note both versions
+
+vphone-launchpad-cli vm create cmp-a --bundle 2.4.0-local.aaaaaaaa
+vphone-launchpad-cli vm create cmp-b --bundle 2.4.0-local.bbbbbbbb
+```
+
+この方法で作成したマシンは、3 つの層すべてが異なります(下記をご覧ください)。1 つのブートチェーンでホストプログラムとゲスト環境だけを比較するには、ウィンドウでマシンを複製し、そのコピーの紐付けを変更します。
+
+```sh
+vphone-launchpad-cli vm set-bundle cmp-b 2.4.0-local.bbbbbbbb --update-environment
+```
+
+`vm list` に、各層がどのバンドルから来たかが表示されます。`bundle remove` は、マシンが紐付いているバージョンを拒否します。先にそれらのマシンの紐付けを変更するか、削除してください。
+
+## マシンとバンドルの紐付け
+
+各マシンは、インストールされた 1 つのバージョンに紐付いています。紐付けは作成時に選ばれ、マシンのフォルダ内の `launchpad.json` に保存されます。バンドルをインストールしても、マシンの紐付けは変わりません。
+
+マシンは 3 つの層からなり、それぞれ異なるタイミングでバンドルから取得されます。
+
+| 層 | 内容 | 取得元 |
+| --- | --- | --- |
+| Host Programs | `vphone-cli`、`vphone-vm` | コマンドのたびに、紐付いたバンドルから。新しい紐付けは次回の起動から反映されます。 |
+| Guest Environment | vphoned とフック用の dylib | 作成時の `cfw install`、その後は `cfw update-environment`(停止中のマシン)。 |
+| Boot Chain | パッチ済みファームウェア、復元、CFW パッチ | 作成時の `fw patch`、`restore`、`cfw install`。 |
+
+### 後からブートチェーンのパッチを変更する
+
+`vphone-cli fw set-patches` でパッチの選択を変更し、`vphone-cli fw patches <vm>` でまだゲストに反映されていないものを一覧表示します。Launchpad ではその数がインスペクタに表示されます。パッチの種類ごとに、ゲストに反映される方法が異なります。
+
+| パッチ | 反映されるタイミング |
+| --- | --- |
+| ゲストパッチ | 次の `cfw update-environment` |
+| AVPBooter | 次の `fw patch` |
+| カーネルパッチ | `cfw update-kernel`(データを保持し、復元ツリーは不要) |
+| ブートチェーンの残り(TXM、DeviceTree、LLB) | 復元のみ(ゲストは消去されます) |
+
+## 標準のバンドル
+
+**default**(標準)のバンドル(以前の名称は「active」)が決めるのは、次のことだけです。
+
+- `--bundle` を指定しないときに `vm create` が紐付けるバージョン
+- `exec` とライブラリ全体に対するコマンドが使うバージョン
+
+`--keep-default` を指定しない限り、新しくインストールしたバンドルが標準になります。Launchpad のセッションでマシンを初めて起動するときに、そのバンドルが一度だけチェックされます(実行ポリシーの例外、AMFI、ホストの事前チェック)。
+
+## バージョン名
+
+ローカルビルドは `<version>-local.<hash>` としてインストールされます。ハッシュはバンドルのコード署名のシールから取られるため、同じバージョンの 2 つのビルドを並べて置けます。古いストアには、`<version>-local` や `<version>-ci.<commit>` が残っていることがあります。
+
+## 関連項目
+
+- [Launchpad コマンドライン](launchpad-cli.md)
+- [バンドルの組み込み](bundle-integration.md)
+- [ダウンロード](../get-started/downloads.md)
diff --git a/Documents/ja/launchpad/launchpad-cli.md b/Documents/ja/launchpad/launchpad-cli.md
new file mode 100644
index 00000000..61eef34e
--- /dev/null
+++ b/Documents/ja/launchpad/launchpad-cli.md
@@ -0,0 +1,180 @@
+# Launchpad コマンドライン
+
+`vphone-launchpad-cli` は、実行中の Launchpad をターミナルやスクリプトから操作します。バンドルのインストール、マシンの作成、起動、停止、ゲストとのやり取りができます。ウィンドウをクリックして回らずに Launchpad の機能を使いたい場合に使います。
+
+## 準備する
+
+CLI は `vphone-launchpad.app/Contents/MacOS` に同梱されています。`PATH` にリンクを作成します。
+
+```sh
+ln -s /Applications/vphone-launchpad.app/Contents/MacOS/vphone-launchpad-cli /usr/local/bin/
+vphone-launchpad-cli help
+```
+
+Launchpad が実行されていない場合は、CLI が Launchpad を起動します。CLI が起動した Launchpad は非表示で開き、前面のアプリからフォーカスを奪いません。ウィンドウを表示するには、Dock アイコンをクリックするか、メニューバーの Open Launchpad を選びます。代わりにウィンドウを前面にして起動するには、`--foreground` を指定します(コマンドの前、または `exec` 以外の任意のコマンドのオプションの中に置きます)。どちらも、すでに実行中の Launchpad には影響しません。
+
+## 出力と終了ステータス
+
+- 進行状況の行は、発生するたびに stderr に出力されます。
+- 結果は 1 つの JSON ドキュメントとして stdout に出力されます。
+- 終了ステータスは成功時に 0、失敗時に 1 で、理由は stderr に出力されます。
+- CLI を中断すると、取り消せるコマンド(`exec`、待機、CFW のインストール)は取り消されます。バンドルのインストールとマシンの作成はウィンドウに属するため、実行が続きます。
+
+すべてのコマンドは、Launchpad のウィンドウとコマンド履歴にも表示されます。
+
+## コマンド
+
+2 つのライブラリに同じ名前のマシンがある場合、マシンのコマンドには `--root <library>` を指定します。
+
+### 状態とバンドル
+
+| コマンド | 内容 |
+| --- | --- |
+| `status` | ホストのチェック、ヘルパー、標準のバンドル、マシンの数 |
+| `bundle list` | インストール済みのバージョン、レシート、cdhash、チェック結果、紐付いたマシン |
+| `bundle install-local <path> [--keep-default]` | ローカルの `VPhone.bundle` フォルダまたは `.zip` をインストールします |
+| `bundle install-release <version\|latest> [--keep-default]` | GitHub のリリースをダウンロードしてインストールします |
+| `bundle set-default <version>` | バージョンを標準にします。`bundle use` は以前の名前です |
+| `bundle verify <version>` | バージョンを再チェックします |
+| `bundle accept <version> [--off]` | 失敗したチェックを無視します。`--off` で無視をやめます |
+| `bundle remove <version>` | どのマシンも紐付いていないバージョンを削除します |
+
+ローカルビルドのインストール、マシンのローカルビルドへの移行、2 つのビルドの比較については、[Core Bundle とローカルビルド](core-bundles.md)をご覧ください。
+
+### マシン
+
+| コマンド | 内容 |
+| --- | --- |
+| `vm list` | すべてのライブラリのマシンと、その実行状態、Core Bundle、ログのパス |
+| `vm start <name> [--headless] [--wait]` | マシンのバンドルで起動します。`--wait` で vphoned を待ちます |
+| `vm stop <name>` | ゲストにシステム終了を求め(vphoned の `system.shutdown`)、最大 30 秒待ちます。ゲストに求められない場合や停止しない場合は、仮想マシンを終了します |
+| `vm wait <name>` | vphoned を待ちます |
+| `vm log <name> [--lines <n>] [--kind create\|dfu\|patch]` | コンソールログを読み取ります |
+| `vm create <name> [options]` | New Machine の処理です。下記の「マシンを作成する」をご覧ください |
+| `vm set-bundle <name> <version> [--update-environment]` | マシンを別のインストール済みバージョンに紐付けます |
+| `vm leases [--release]` | 共有 NAT ネットワーク上の DHCP リースと、それぞれを所有するマシン。`--release` は、どのライブラリのどのマシンも使っていないリースをヘルパーを通じて解放します([MAC アドレスと IP アドレス](../networking/addresses.md)の「古い MAC が保持しているアドレス」をご覧ください) |
+
+注意:
+
+- `vm list` でマシンが `running` になるのは、ディスクを保持しているのが仮想マシンのプロセス(`vphone-vm`、または Virtualization の仮想マシンサービス)の場合だけです。ディスクを開いているほかのプロセス(`tail`、Spotlight、バックアップツール)は `diskOpenIn` に表示され(例:`12925 tail`)、マシンは `stopped` のままです。
+- `vm start` は、`vphone-cli vm launch` と同じく、ディスクを開いているだけのプロセスがあっても拒否されません。そのプロセスの名前を示すメモが表示されます。
+- `vm start --wait` と `vm wait` は `--timeout` も受け付けます。
+- `vm set-bundle --update-environment` は、そのバージョンのゲスト環境も配置し直すため、マシンを停止しておく必要があります。ほかのプロセスがディスクを開いている場合は、紐付けを変更する前に、そのプロセスの名前を示して拒否されます。更新自体が失敗した場合、マシンは新しいバージョンに紐付いたままで、`vm list` には古い `guestEnvironmentBundle` が表示されたままになります。`cfw update-environment` を実行して完了させてください。
+
+### CFW
+
+これらは停止中のマシンに対し、マシン自身のバンドルを使って Launchpad のヘルパーを通じて実行されます。ほかのプロセスがディスクを開いている場合は、そのプロセスの名前(`12925 tail`)を示してそれぞれ拒否されます。
+
+| コマンド | 内容 |
+| --- | --- |
+| `cfw install <name>` | CFW をインストールします。該当する場合、ヘルパーは一時的な作業ファイルを仮想マシンのライブラリの外部ボリュームに置きます |
+| `cfw update-environment <name>` | バンドルのゲストリソース(vphoned、フック用の dylib)を配置し直します。ほかには何も変わりません |
+| `cfw update-kernel <name>` | マシンの現在のパッチの選択で kernelcache にパッチを適用し直し、データを保持したまま Preboot の kernelcache と入れ替えます。インストール済みの仮想マシンでデータを保持したままカーネルパッチを変更する方法です。復元ツリーは必要ありません |
+
+### ゲスト
+
+`guest` コマンドと `--wait` は、マシンの `vphone.sock` を通じて動作します。このソケットはすべての起動で提供されます。2.0.9 までのバンドルでは、ウィンドウ付きで起動したマシンでのみ提供されます。
+
+| コマンド | 内容 |
+| --- | --- |
+| `guest send <name> <json>` | `vphone.sock` への生のリクエストを 1 つ送ります(tap、swipe、key、screenshot) |
+| `guest rpc <name> <method> [params]` | 任意の vphoned メソッドを呼び出します。[`Research/vphoned_http_api.md`](../../../Research/vphoned_http_api.md) をご覧ください。vphoned が拒否した場合、stderr の最後の行がそのエラーオブジェクトの JSON(`code`、`message`、`results`、`reason` …)になります |
+| `guest push <name> <local> <guest-path> [--mode <octal>]` | Mac のファイルをゲストにコピーします。vphoned を通じてストリーミングするため、サイズは `guest rpc` の 1 MiB の JSON 行に制限されません。バイナリや IPA に使います。ゲストのパスが `/` で終わる場合はファイル名がそのまま使われます。モードの標準は Mac のファイルのアクセス権です |
+| `guest pull <name> <guest-path> <local>` | ゲストのファイルを Mac にストリーミングでコピーします。`local` にはフォルダも指定できます。ファイルが `local` を置き換えるのは、コピーが完了してからです |
+| `guest unlock <name> [--passcode <code>] [--timeout <seconds>]` | ゲストがどの状態でも、画面をオンにしてロックを解除します(vphoned の `screen.unlock`)。`--passcode` は、ゲストにパスコードが設定されている場合にのみ必要です |
+
+### vphone-cli を実行する
+
+| コマンド | 内容 |
+| --- | --- |
+| `exec [--bundle <version>] <vphone-cli arguments>` | 標準のバンドル、または指定したバージョンの `vphone-cli` を実行し、その出力をストリーミングします。`--bundle` は最初に置く必要があります |
+
+## マシンを作成する
+
+`vm create` は、`--bundle <version>` または標準のバンドルに紐付けて New Machine の処理を実行します。マシンはテンプレートから複製され、テンプレートがない場合は先に作成されます(2.9)。`--no-template` を指定すると単独で復元されます。
+
+```sh
+vphone-launchpad-cli vm create rt-e --block system-debugserver-cfw-install
+```
+
+| オプション | 内容 |
+| --- | --- |
+| `--bundle <version>` | 標準のバンドルの代わりに、このインストール済みバージョンにマシンを紐付けます |
+| `--device <product-type>` | 別のデバイスを作成します。下記の「その他のデバイス」をご覧ください |
+| `--preset <preset>` | プリセットの名前、またはプリセットの plist のパス(2.14)。マシンはそのコピーを保持します |
+| `--block <patch>`、`--allow <patch>` | プリセットのパッチを 1 つオフまたはオンにします。繰り返し指定できます。下記の「パッチの上書き設定」をご覧ください |
+| `--no-template` | テンプレートを複製せず、マシンを単独で復元します |
+| `--slim on\|off`、`--trim …`、`--keep-languages …`、`--service-profile …`、`--remove-apps …`、`--keep-apps …` | `vphone-cli vm create` の軽量化のスイッチ。New Machine と同じく、Apple アカウントは trimmed のサービスプロファイルに従います |
+| `--accounts-off` | 受け付けますが、何も変わりません |
+| `--ipsw <path>` | 省略可能。2.12.0 のバンドルにだけ渡され、New Machine の ipsw 欄と同じく、kernelcache ミックスの準備に使われます。2.12.1 のバンドルはネイティブで展開します |
+| `--kmutil-ssh <user@host>` | New Machine の macOS ビルダー欄と同じく、iOS 18 ゲスト(`--device iPhone11,6`)の kernel-first のミックスを ssh 経由でリンクする Mac。そこでの ssh と sudo のパスワードは、引数ではなく、クライアントの `VPHONE_KMUTIL_SSH_PASSWORD` から取得します |
+| `--from <step>` | 作成開始時のオプションで、ある手順(`findTemplate` … `firstBoot`)からやり直します |
+
+パーサは `--iphone-source`、`--cloudos-source`、`--cpu`、`--memory`、`--disk-size`、`--network`、`--keep-artifacts`、`--no-wait` も受け付けます。`vphone-launchpad-cli help` をご覧ください。
+
+結果には、テンプレート、この作成処理がそのテンプレートを作ったかどうか、使用したパッチが表示されます。
+
+### その他のデバイス
+
+| `--device` | ゲスト | 備考 |
+| --- | --- | --- |
+| iPad の製品タイプ | iPadOS | [iPadOS ゲスト](../firmware/ipados.md)をご覧ください |
+| `AppleTV5,3` | Apple TV HD | 常に軽量化なしで単独で復元されます。`--preset` で別のプリセットを指定しない限り、`tvos` プリセットを使います |
+| `AppleTV14,1` | Apple TV 4K(第 3 世代) | 同様で、`tvos-4k` プリセットを使い、ユーザランドはカタログの OTA から取得します |
+| `AppleTV18,1` | Apple TV 4K(第 4 世代) | Launchpad と Core Bundle 2.13 が必要です。`tvos-4k` を選び、軽量化なしで単独で復元し、Apple TV HD のベースに重ねたフル OTA から tvOS 27.2 ベータ(`24K120`)を取得します。作成には macOS 27 が必要です。実際の起動はまだ確認されていません。[立ち上げの記録](../../../Research/Firmware/tvos_support.md#apple-tv-4k-4th-generation)をご覧ください |
+
+さらに 2 つの場合では、ヘルパーを通じて root として手順が実行されます。
+
+- `--preset minimal`(Minimal:未変更のブートチェーン、カーネル、TXM を使い、復元前にシステムをカスタマイズします)も軽量化なしで単独で復元され、その `fw patch` はヘルパーを通じて root として実行されます。Userspace debugging のボックス(`vphone-cli fw patches` の Features にある `userspace-debugging`)は、そこに記載された各パッチに対する `--allow` です。
+- cloudOS に vphone600 のコンポーネントがないマシン(そのリリース自身の cloudOS、Watch、iOS 18 ゲスト)では、kernelcache ミックスを `fw kernelcache` で準備し、ヘルパーが root としてリンクします。
+
+### パッチの上書き設定
+
+`--block <patch>` と `--allow <patch>` には、`vphone-cli fw patches` が表示する識別子を、パッチごとに 1 回ずつ指定します。
+
+```sh
+vphone-launchpad-cli exec fw patches --preset <preset>
+```
+
+Launchpad は作成処理のバンドルからそのカタログを読み込み、どのパッチセットにも宣言されていない識別子や、ブロックと許可の両方に指定された識別子を拒否し、`fw set-patches` と同じく、プリセットと異なるものだけを保持します。その後、New Machine と同じ方法でそれらを分けます。
+
+- **ブートチェーンのパッチ**(AVPBooter、iBSS、iBEC、LLB、TXM、kernelcache、DeviceTree …)はテンプレートのキーに含まれます。Find Template はそれを適用して作られたテンプレートを探し、テンプレートの作成処理は `fw patch` の前に `fw set-patches` でそれを記録します。
+- **ゲストパッチ**はテンプレートに含まれません。複製は `fw set-patches` でそれを記録し、Apply Guest Patches の手順で、初回起動の前にヘルパーを通じて `cfw update-environment` で書き込みます。そのため、ゲストの上書き設定だけであれば、通常のテンプレートが再利用されます。
+
+結果の `patches` オブジェクトには、プリセット、`blocked` と `allowed` の上書き設定、複製に適用された `guest` の上書き設定が含まれます。`--no-template` の場合、すべての上書き設定はマシン自身の復元に反映されます。`--from` は `--block` と `--allow` を拒否します。やり直す場合は、作成処理のパッチがそのまま使われます。
+
+## 結果に含まれるバンドルのフィールド
+
+| コマンド | フィールド | 意味 |
+| --- | --- | --- |
+| `status` | `defaultBundle` | 標準のバージョン。古いスクリプトのために、`activeBundle` にも同じ値が入ります |
+| `bundle list` | `default` | このバージョンが標準であること。古いスクリプトのために、`active` にも同じ値が入ります |
+| `bundle list` | `machines` | このバージョンに紐付いたマシンの名前 |
+| `vm list` | `bundle` | マシンのホストプログラムが使うバージョン |
+| `vm list` | `guestEnvironmentBundle` | 最後にゲスト環境をインストールしたバージョン。不明な間は `null` |
+| `vm list` | `bootChainBundle` | ブートチェーンを作ったバージョン。Launchpad が記録するようになる前に作成されたマシンでは `null` |
+| `vm create`、`cfw …`、`exec` | `bundle` | コマンドが使ったバージョン |
+
+`guestEnvironmentBundle` が `bundle` と異なる場合、ホストとゲストは別のビルドのものです。`cfw update-environment` でゲストを合わせられます。
+
+## タッチ座標とディスプレイの形状
+
+`guest send` のタッチ座標は、`t:screenshot` が返す**直立したスクリーンショット全体**を基準にします。90 度回転すると、幅と高さが入れ替わります。ホストは、GUI でもヘッドレスでも、その座標を固定パネルの HID 座標に変換します。スワイプは、開始時に取得した形状を使い続けます。スクリーンショットの間に形状が変わった場合は、入力座標があいまいな画像の代わりにエラーが返されます。
+
+回転時の座標のずれを診断するには、形状を読み取ります。
+
+```sh
+vphone-launchpad-cli guest send <name> '{"t":"display.geometry"}'
+```
+
+ホストで設定されたピクセル寸法と取得したピクセル寸法に加え、表示中のディスプレイビューの境界、回転、アスペクト比を保った描画領域、ポインタとタッチの経路が返されます。入力やディスプレイの状態は何も変わりません。`capture_pixels` はホストの生のフレームで、`screenshot_pixels` と `input_orientation` は入力座標を表します。`device.screen`、`display.orientation`、ゲストが実際に受け取るイベントと比較してください。
+
+## 接続の仕組み
+
+CLI は、`~/Library/Application Support/vphone-launchpad/control.sock`(モード 0600、同じユーザにのみ提供)の Unix ソケットを通じて、実行中の Launchpad と通信します。CLI は権限も独自の状態も持ちません。バンドルは Launchpad のヘルパーを通じてインストールされ、各マシンは自身の Core Bundle の `vphone-cli` を通じて実行されます。ネットワークでリッスンするものは何もありません。別のマシンから使うには、ssh で接続してください。
+
+## 関連項目
+
+- [Core Bundle とローカルビルド](core-bundles.md)
+- [バンドルの組み込み](bundle-integration.md)
+- [作成と実行](../machines/create-and-run.md)
diff --git a/Documents/ja/machines/automation-api.md b/Documents/ja/machines/automation-api.md
new file mode 100644
index 00000000..90e6990d
--- /dev/null
+++ b/Documents/ja/machines/automation-api.md
@@ -0,0 +1,78 @@
+# 自動化 API
+
+実行中の仮想マシンを、HTTP と WebSocket を使ってスクリプトから操作します。このページでは、API の有効化、認証、最初の呼び出しまでを説明します。すべてのルートとメソッドは [API の完全なリファレンス](../../../Research/vphoned_http_api.md)に記載されています。
+
+## 有効にする
+
+仮想マシンの起動時に `--api-listen` を追加します。
+
+```sh
+vphone-cli vm launch myphone --api-listen 127.0.0.1:8765
+```
+
+仮想マシンが起動すると、`vphone-vm` がアドレスとトークンを表示します。
+
+```text
+[api] HTTP/WebSocket API: http://127.0.0.1:8765
+[api] token: 3f9c…
+[api] send it as: Authorization: Bearer 3f9c…
+```
+
+- `--api-listen` を指定しないと、ホスト側でリッスンするものはありません。
+- ポート `0` を指定すると、macOS に空いているポートを割り当てさせます。実際のアドレスは仮想マシンの起動後に表示されます。
+- `--api-listen` は `--dfu` と併用できません。
+
+> [!WARNING]
+> vphoned は root として動作し、API はゲストの任意のファイルの読み書き、キーチェーンの一覧表示、launch daemon の読み込みができます。ローカルだけで使う場合は、`127.0.0.1` または `[::1]` でリッスンしてください。それ以外のアドレスでは警告が表示されます。そのアドレスに到達できるマシンはトークンさえあれば操作でき、トークンは平文の HTTP でそのまま送られるため、信頼できるネットワークでのみ使用してください。
+
+## トークン
+
+トークンは起動のたびに新しく生成されます(32 バイトの乱数を 16 進数で表したもの)。トークンを固定するには、起動前に `VPHONE_API_TOKEN` を設定します。`vphone-cli vm launch` は自身の環境変数を `vphone-vm` に引き継ぎます。値は `A-Z a-z 0-9 - . _ ~` からなる 16〜256 文字である必要があります。それ以外の空でない値を設定すると、起動は中止されます。
+
+トークンは次のどの形式でも送れます。
+
+| 形式 | 用途 |
+| --- | --- |
+| `Authorization: Bearer <token>` ヘッダ | HTTP、およびヘッダを設定できる WebSocket クライアント |
+| `token=<token>` クエリ項目 | `ws://127.0.0.1:8765/v1/events?token=<token>` のような WebSocket の URL |
+| `Sec-WebSocket-Protocol: vphone-token.<token>` | サブプロトコルしか設定できない WebSocket クライアント |
+
+トークンがない、または間違っている場合は `401 Unauthorized` が返され、ゲストに何かが届く前に接続が閉じられます。
+
+## 呼び出しの例
+
+```sh
+TOKEN=... # from the "[api] token:" line, or the VPHONE_API_TOKEN you set
+
+# Health check
+curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8765/v1/health
+
+# Call any method through /v1/rpc
+curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+ -d '{"method":"device.snapshot","params":{}}' http://127.0.0.1:8765/v1/rpc
+
+# Event stream
+websocat "ws://127.0.0.1:8765/v1/events?token=$TOKEN"
+
+# Interactive shell in the guest (websocat needs --binary)
+websocat --binary "ws://127.0.0.1:8765/v1/shell?token=$TOKEN&cols=120&rows=40"
+```
+
+自作のクライアントでつまずきやすい規則:
+
+- すべての `POST` で `Content-Type: application/json` を送る必要があります。送らないと `415` が返されます。
+- `Origin` ヘッダのあるリクエスト、または `Host` が `vphoned`、`localhost`、`127.0.0.1`、`::1` 以外のリクエストには `403` が返されます。これにより、ブラウザのページから API にアクセスできないようにしています。
+- `GET` のルートは読み取りだけを行います。設定を変更するには `PUT` または `POST` を使います。たとえば `PUT /v1/low-power-mode` に `{"enabled": true}` を送ります。
+
+Swift のアプリでは、`VPhoneAPIKit` パッケージの `VPhoneAPIClient` を使えます。トークンは自動で送られます。例はリファレンスをご覧ください。
+
+## ネットワークでリッスンせずに使う
+
+仮想マシンの制御ソケットは、API のリスナーがなくても同じメソッドを受け付けます。`{"t":"rpc","method":"<method>","params":{}}` を 1 行の JSON として送ってください。[仮想マシンの作成と実行](create-and-run.md)の「制御ソケット」をご覧ください。
+
+## 関連項目
+
+- [API の完全なリファレンス](../../../Research/vphoned_http_api.md)
+- [仮想マシンの作成と実行](create-and-run.md)
+- [ポート転送](../networking/port-forwarding.md)
+- [Launchpad コマンドライン](../launchpad/launchpad-cli.md)
diff --git a/Documents/ja/machines/boot-roms.md b/Documents/ja/machines/boot-roms.md
new file mode 100644
index 00000000..7eabc238
--- /dev/null
+++ b/Documents/ja/machines/boot-roms.md
@@ -0,0 +1,51 @@
+# ブート ROM
+
+仮想マシンが起動に使うブート ROM と SEP ブート ROM を選びます。このページでは、仮想マシンが使っている ROM の確認方法と、オープンソースの ROM と Apple の ROM の切り替え方法を説明します。
+
+## 確認と切り替え
+
+```sh
+vphone-cli vm info myphone # shows rom and seprom
+vphone-cli vm config myphone --rom openavb --seprom opensep # open-source ROMs
+vphone-cli vm config myphone --rom apple --seprom apple # Apple's ROMs
+```
+
+切り替えは、どちらの方向でも復元なしで、仮想マシンの次回の起動から反映されます。
+
+| オプション | 値 | ROM |
+| --- | --- | --- |
+| `--rom` | `openavb` | バンドルに含まれる OpenAVB |
+| `--rom` | `apple` | Virtualization.framework の AVPBooter(マシン専用のパッチ済みコピーがある場合はそれ) |
+| `--rom` | ファイルのパス | その他の任意のブート ROM |
+| `--seprom` | `opensep` | バンドルに含まれる OpenSEP |
+| `--seprom` | `apple` | Virtualization.framework の AVPSEPBooter |
+| `--seprom` | ファイルのパス | その他の任意の SEP ブート ROM |
+
+どちらのブート ROM も同じパッチ済みの LLB を読み込み、どちらの SEP ROM も復元時にインストールされた SEP ファームウェアを読み込みます。そのため、復元は必要ありません。
+
+> [!NOTE]
+> OpenAVB で起動する仮想マシンを復元するには、`VPhone.bundle` 2.10.1 以降が必要です。
+
+## 仮想マシンが使う ROM
+
+新しい仮想マシンは、Virtualization.framework に含まれるクローズドな ROM ではなく、2 つのオープンソースの ROM から起動します。
+
+- [OpenAVB](https://github.com/owngoal-dev/OpenAVB) はブート ROM である AVPBooter の代わりです。パッチが不要なので、`fw patch` は変更を加えません。
+- [OpenSEP](https://github.com/owngoal-dev/OpenSEP) は SEP ブート ROM である AVPSEPBooter の代わりです。
+
+両方を使うと、iBoot と SEPOS より前に実行されるコードに Apple が書いたものはなくなります。以前のバージョンで作成した仮想マシンは、切り替えるまで Apple の ROM を使い続けます。
+
+## ROM の出どころ
+
+どちらの ROM も、固定した上流のコミットからビルドされた状態で `VPhone.bundle` に含まれています。それぞれの README に、ビルドし直してバイト単位で照合する方法が記載されています。
+
+- [OpenAVB の README](../../../VPhoneExecutable/VPhoneVirtualization/Resources/OpenAVB/README.md)
+- [OpenSEP の README](../../../VPhoneExecutable/VPhoneVirtualization/Resources/OpenSEP/README.md)
+
+詳しくは、[OpenAVB](../../../Research/Firmware/openavb_boot_rom.md) と [OpenSEP](../../../Research/Firmware/opensep_sep_rom.md) の研究記録をご覧ください。
+
+## 関連項目
+
+- [仮想マシンの作成と実行](create-and-run.md)
+- [ファームウェアの準備](../firmware/firmware-preparation.md)
+- [トラブルシューティング](../help/troubleshooting.md)
diff --git a/Documents/ja/machines/create-and-run.md b/Documents/ja/machines/create-and-run.md
new file mode 100644
index 00000000..301b6cdc
--- /dev/null
+++ b/Documents/ja/machines/create-and-run.md
@@ -0,0 +1,121 @@
+# 仮想マシンの作成と実行
+
+ターミナルで `vphone-cli` を使って仮想マシンを作成、起動、停止します。Launchpad を使わずに作業する場合、仮想マシンの作成をスクリプト化する場合、処理の一部の段階だけをやり直す場合にこのページを使います。
+
+Launchpad は `VPhone.bundle` 内の `vphone-cli` を使って仮想マシンを操作しています。同じコマンドはターミナルでも使えます。
+
+```sh
+vphone-cli vm list
+vphone-cli vm launch myphone
+vphone-cli vm export myphone --out myphone.tzst
+```
+
+仮想マシンは `~/.vphone/` に保存されます。すべてのコマンドは `vphone-cli <group> --help` で確認できます。
+
+## 仮想マシンを作成する
+
+iPhone17,3 の復元用 IPSW と、互換性のある PCC/cloudOS の IPSW が必要です。ローカルのパスでも URL でも指定できます。これまでに検証された組み合わせは[互換性](../firmware/compatibility.md)に記載されています。
+
+```sh
+vphone-cli host preflight
+vphone-cli vm create myphone \
+ --iphone-source /path/to/iPhone17,3_Restore.ipsw \
+ --cloudos-source /path/to/cloudOS.ipsw
+```
+
+作成は次の段階で進みます:準備、ファームウェアへのパッチ適用、オンラインでの DFU 復元、ホスト側でマウントしての CFW インストール、GUI での初回起動。
+
+- 復元チケットを取得するためにネットワーク接続が必要です。
+- CFW のインストールには root 権限が必要です。バンドルには認証ダイアログも権限昇格用のヘルパーもないため、root 権限は自分で用意してください。
+- 仮想ディスクの標準サイズは 64 GB です。
+
+成功すると、最後に `[+] First boot: vphoned ping succeeded.` と `CFW VM created; vphoned connected. Guest user environment is untouched.` が表示されます。その後、仮想マシンは停止します。ping はその起動中に vphoned が応答したことを確かめるもので、実行中の仮想マシンは残りません。
+
+### オプション
+
+| オプション | 効果 |
+| --- | --- |
+| `--iphone-version`、`--iphone-build` | `--iphone-source` を渡す代わりに、`fw prepare` と同じ方法で `--device`(標準は iPhone17,3)向けの iPhone IPSW を特定します。 |
+| `--cloudos-source` を省略 | `fw catalog` が示す、そのリリースに推奨される cloudOS を使います。 |
+| `--disk-size` | 仮想ディスクのサイズ(GB、標準は 64)。 |
+| `--preset` | パッチプリセットの名前、またはプリセットの plist のパス(標準は `standard`)。各プリセットが適用するパッチは `fw patches` で確認できます。 |
+| `--cpu` | CPU コア数(標準は 8)。 |
+| `--memory` | メモリ(MB、標準は 8192)。 |
+| `--network` | `nat`(標準)、`bridged`、`tunnel`、`none` のいずれか。 |
+| `--unlock-at-startup` | `on` または `off`(標準)。 |
+| `--no-template` | テンプレートから複製せず、仮想マシンを単独で作成します。 |
+| `--skip-first-boot` | 最後の起動を省きます。呼び出し側が自分で仮想マシンを起動する場合に使います。 |
+| `--bootstrap roothide` | 初回起動中にパッケージ環境をインストールします。[パッケージ環境](package-environment.md)をご覧ください。 |
+| `--keep-artifacts` | 準備した大きな復元ツリーを残します。ディスク容量が気になる場合は指定しないでください。 |
+
+`--cpu`、`--memory`、`--network`、`--unlock-at-startup` は、新しい仮想マシンに `vm config` の同じ設定を行います。
+
+### テンプレート
+
+標準では、作成処理は[テンプレート](../storage/templates.md)を作り、そこから仮想マシンを複製します。同じデバイス、iOS と cloudOS のビルド、プリセット、ディスクサイズで次に `vm create` を実行すると、復元し直さずにそのテンプレートから複製します。仮想マシンを単独で作成するには `--no-template` を指定します。
+
+### パッチとファームウェアの準備
+
+ファームウェアの処理には 1 つのモードしかありません。ブートチェーンとゲストのシステムにパッチを適用し、vphoned をインストールし、ユーザ環境は空のままにします。Sileo、apt、TrollStore、SSH サーバ、VNC サーバはインストールしません。適用するパッチはパッチプリセットで選びます。`vphone-cli fw set-patches` に `--block` または `--allow` を付けると、個々のパッチをオフまたはオンにできます。
+
+パッチを適用する前に、作成処理はファームウェアを準備します。一時的な cloudOS の復元から GPU ドライバを取り出し、vphone600 のコンポーネントを含まない cloudOS の場合は kernelcache を作り直します。[ファームウェアの準備](../firmware/firmware-preparation.md)をご覧ください。1 つのリストから複数のマシンを作成するには、[複数マシンの一括作成](../storage/many-machines.md)をご覧ください。
+
+## 起動と停止
+
+```sh
+vphone-cli vm launch myphone # start the VM window and keep it running
+vphone-cli vm stop myphone # run from another terminal to stop it
+```
+
+`vm launch` は vphoned を待たずにゲストを起動します。デーモンは起動中に接続します。仮想マシンのウィンドウとメニューには、ホームボタンと電源ボタン、アプリのインストール、ファイルの閲覧の機能があります。`vm launch --headless` は、仮想マシンのウィンドウとメニューバーなしで起動します。
+
+次のどの操作でも、ゲストは正常にシステム終了します(vphoned の `system.shutdown`)。
+
+- 仮想マシンのウィンドウを閉じる
+- ⌘Q
+- `vm stop`
+- `vm launch` を実行したターミナルで Control-C
+
+仮想マシンは、ゲストが停止した時点、または停止しない場合は 15 秒後に終了します。DFU 中や起動途中など、vphoned が応答できない状態のゲストは、電源を抜いたときのようにすぐに電源が切られます。Control-C をもう一度押すと、待たずに電源を切ります。
+
+`vm stop` がシグナルを送るのは、そのマシン自身のプロセス、つまり `vphone-vm` と Virtualization の仮想マシンサービスだけです。サイズを計測中の Launchpad、Spotlight、バックアップツールなど、ディスクを開いているほかのプログラムは、名前が表示されるだけで実行されたままになります。
+
+## 制御ソケット
+
+実行中の各仮想マシンには、そのフォルダ内の `vphone.sock`(`~/.vphone/machines/<name>/vphone.sock`)に制御ソケットがあります。1 行の JSON を送ると、1 行の JSON が返ります。複数の接続は並行して処理されます。ウィンドウのない仮想マシンにもこのソケットはあり、その場合 `tap` と `swipe` は vphoned のタッチ注入を通じて行われ、画面の画像はゲストから取得されます。
+
+`tap`、`swipe`、`key`、`screenshot` に加え、`rpc` リクエストで [API リファレンス](../../../Research/vphoned_http_api.md)にある任意の vphoned メソッドを呼び出せます。
+
+```sh
+printf '%s\n' '{"t":"rpc","method":"device.info","params":{}}' | nc -U ~/.vphone/machines/myphone/vphone.sock
+```
+
+たとえば、`input.key` に `{"name":"cmd+v"}` を渡すとペーストし、`input.type` でテキストを入力します。この処理では SSH や VNC のエンドポイントはインストールされません。HTTP と WebSocket でアクセスするには、[自動化 API](automation-api.md) をご覧ください。
+
+## 各段階を手動で実行する
+
+調査する場合や、ある段階だけをやり直す場合に使います。`restore` が通信している間は、DFU で起動した状態を保ってください。
+
+```sh
+vphone-cli vm new myphone
+vphone-cli fw prepare myphone \
+ --iphone-source /path/to/iPhone17,3_Restore.ipsw \
+ --cloudos-source /path/to/cloudOS.ipsw
+vphone-cli fw patch myphone
+
+vphone-cli vm launch myphone --dfu &
+vphone-cli restore myphone
+vphone-cli vm stop myphone
+
+vphone-cli cfw install myphone
+vphone-cli vm launch myphone
+```
+
+オンラインの復元では、プロセス内でチケットを取得します。オフラインで復元するには、`vphone-cli restore --help` で `--get-shsh` と `--offline` を確認してください。手動の手順では、`vm create` が行う初回起動の ping チェックは実行されません。
+
+## 関連項目
+
+- [テンプレート](../storage/templates.md)
+- [デバイス名と時計](device-name-and-clock.md)
+- [ライブラリとバックアップ](../storage/library-and-backups.md)
+- [ディスク容量の共有](../storage/sharing-disk-space.md)
diff --git a/Documents/ja/machines/device-name-and-clock.md b/Documents/ja/machines/device-name-and-clock.md
new file mode 100644
index 00000000..871e46fc
--- /dev/null
+++ b/Documents/ja/machines/device-name-and-clock.md
@@ -0,0 +1,42 @@
+# デバイス名と時計
+
+ゲストは、デバイス名を仮想マシンから、時計と時間帯を Mac から受け取ります。ゲストの名前や時刻が思ったとおりでない場合にこのページをご覧ください。
+
+## デバイス名
+
+ゲストに表示される名前を変えるには、仮想マシンの名前を変更します。
+
+```sh
+vphone-cli vm rename myphone <new-name>
+```
+
+ゲストは仮想マシンの名前をデバイス名として表示します。Xcode のデバイス一覧や `xcrun devicectl list devices` でも同じ名前になります。
+
+- ゲストの中や、Finder、Xcode、`idevicename` からはデバイス名を変更できません。そこで名前を変更すると成功したと表示されますが、何も変わりません。
+- `vm rename` の後、Finder と `ideviceinfo` ではマシンが起動するとすぐに新しい名前が表示されます。Xcode と `devicectl` はデバイスが現れたときに名前を読み取るため、次の起動までは古い名前が表示されることがあります。
+- 仮想マシン名が UTF-8 で 255 バイトを超える場合や制御文字を含む場合は、その名前は使われず、ゲストは自身の名前を表示します。
+
+`vphone-vm` は、起動のたびに数秒後に vphoned に接続した時点で名前をゲストに渡し、ゲストは次の起動時にも使えるようにその名前を保持します。ゲスト自身の名前は環境設定に残り、変更されません。
+
+この機能を持つバンドルに移行した既存のマシンは、環境の更新とともにゲストライブラリを受け取り、その次の起動から使用します。
+
+実装については [`Research/Guest/device_name_pinning.md`](../../../Research/Guest/device_name_pinning.md) をご覧ください。
+
+## 時計と時間帯
+
+ゲストは Mac の時間帯と時計に従います。設定は何も必要ありません。
+
+`vphone-vm` は vphoned に接続するたびに Mac の時間帯を送り、その時点と以後 1 分ごとに Mac の時刻を送ります。1 日電源が切れていたゲストや、スリープ中の Mac の上で止まっていたゲストも、NTP サーバに接続せずに 1 分以内に Mac の時刻に戻ります。Mac との差が 1 秒以内のゲストはそのままにされます。
+
+ゲストに別の日付や時刻を設定するには:
+
+1. ゲストで **設定 > 一般 > 日付と時刻** を開きます。
+2. 日付または時刻を選びます。これによりゲストの自動設定がオフになり、Mac の時刻は適用されなくなります。
+
+Mac の時刻に戻すには、同じ画面で **自動設定** をもう一度オンにします。
+
+## 関連項目
+
+- [仮想マシンの作成と実行](create-and-run.md)
+- [ライブラリとバックアップ](../storage/library-and-backups.md)
+- [ネットワーク](../networking/overview.md)
diff --git a/Documents/ja/machines/package-environment.md b/Documents/ja/machines/package-environment.md
new file mode 100644
index 00000000..a6eddacd
--- /dev/null
+++ b/Documents/ja/machines/package-environment.md
@@ -0,0 +1,50 @@
+# パッケージ環境
+
+仮想マシンにパッケージマネージャをインストールしたり、削除したりします。新しい仮想マシンにはパッケージマネージャがありません。ゲストで `apt`、シェル、SSH などのコマンドラインツールが必要な場合は、このページの手順に従ってください。
+
+## インストール
+
+1. 仮想マシンのウィンドウのメニューバーで **Apps > Install Bootstrap…** を選び、レイアウトとして **roothide** を選択します(**rootless** は非推奨です)。仮想マシンに Irisin がインストールされます。
+2. Irisin で **OwnGoal Packages** リポジトリを開き、**OwnGoal Bootstrap for vphone**(`owngoal-bootstrap-vphone`)を探して **Bootstrap Install** でインストールします。
+3. この初回のインストール後は、ほかのパッケージを通常どおりインストールできます。
+
+`owngoal-bootstrap-vphone` 1 つで、仮想マシンに必要なものが一度にそろいます:`apt` と `dpkg`、`bash`、`zsh` と `dash`、`sudo`、基本的なコマンドラインツール、`openssh-server`、`curl`、`wget`、`vim`、`git`、`uikittools`、`launchctl`、そして OwnGoal のアプリです。
+
+> [!WARNING]
+> これらのパッケージを一つずつインストールしないでください。いくつかのパッケージは相互に依存しており、`openssh-server` には循環した依存の記述があるため、個別にインストールすると途中で失敗することがあります。
+
+初回のインストールに失敗した場合は、その場で修復しようとしないでください。**Apps > Uninstall Bootstrap…** を選んでから、手順 1 からやり直してください。
+
+### 仮想マシンの作成時にインストールする
+
+```sh
+vphone-cli vm create myphone --bootstrap roothide ...
+```
+
+`--bootstrap roothide` は、新しいマシンの初回起動中に手順 1 と 2 を行います。Irisin をインストールし、Irisin が推奨するリポジトリから `irisin-cli` を通じて `owngoal-bootstrap-vphone` を Bootstrap Install でインストールします。手順 2 には、`irisin-cli install` が `--repository` と `--bootstrap-install` に対応している Irisin が必要です。
+
+## 削除
+
+**Apps > Uninstall Bootstrap…** を選びます。削除後、仮想マシンは再起動します。
+
+Irisin はデータ(ダウンロード、ジャーナル、設定)を自身のホーム内の `Documents/wiki.qaq.irisin` に保存します。
+
+| レイアウト | Irisin のホーム | 削除後 |
+| --- | --- | --- |
+| roothide | 環境自身の `/var/mobile` | データもほかのものと一緒に削除されます。 |
+| rootless | システムの `/var/mobile` | データは残ります。 |
+
+## その他のオプション
+
+Option キーを押しながら **Apps** メニューを開くと、さらに 2 つの項目が表示されます。
+
+- **Install Bootstrap from File…:** ローカルの Irisin `.deb` からインストールします。
+- **Uninstall Bootstrap Without Restarting…:** 仮想マシンを再起動せずに環境を削除します。
+
+同じ操作は自動化 API(`bootstrap.install`、`bootstrap.status`)からも行えます。[API リファレンス](../../../Research/vphoned_http_api.md)をご覧ください。
+
+## 関連項目
+
+- [仮想マシンの作成と実行](create-and-run.md)
+- [自動化 API](automation-api.md)
+- [トラブルシューティング](../help/troubleshooting.md)
diff --git a/Documents/ja/networking/addresses.md b/Documents/ja/networking/addresses.md
new file mode 100644
index 00000000..86f2fd19
--- /dev/null
+++ b/Documents/ja/networking/addresses.md
@@ -0,0 +1,80 @@
+# MAC アドレスと IP アドレス
+
+このページでは、ゲストの保存された MAC アドレス、古い MAC が保持したままの DHCP リースの解放、ゲストへの固定 IPv4 アドレスの割り当てについて説明します。
+
+## MAC アドレス
+
+最初の起動時に、ゲストのネットワークカードにはランダムなローカル管理の MAC アドレスが割り当てられ、マシン識別子と同じように `config.plist` に保存されます。これにより、ゲストは起動をまたいで 1 つのアイデンティティと 1 つの DHCP リースを保ちます。
+
+設定または置き換えるには:
+
+```sh
+vphone-cli vm config <name> --mac 02:11:22:33:44:55
+vphone-cli vm config <name> --mac random # a new one now
+vphone-cli vm config <name> --mac auto # a new one at the next launch
+```
+
+複製したマシンは、マシン識別子と同じく元のマシンの MAC を引き継ぎます。両方を同時に実行する前に、コピーに新しいアイデンティティと MAC を与える `vm clone --new-identity` で複製するか、コピーに新しい MAC を設定してください。`--new-identity` は、コピーの固定アドレス、ポート転送、mDNS 名も消去します。
+
+## 古い MAC が保持しているアドレス
+
+症状:`nat` モードで、新しいゲストに割り当てられるアドレスがどんどん大きくなり、範囲の上のほうに選んでおいた固定アドレスに達してしまう。
+
+共有ネットワーク上のリースとそれぞれの所有者を一覧表示してから、孤立したリースを解放します(`VPhone.bundle` 2.5 以降が必要です)。
+
+```sh
+vphone-cli vm leases
+sudo vphone-cli vm leases --release-orphans
+```
+
+Launchpad を通じて行う場合:
+
+```sh
+vphone-launchpad-cli vm leases
+vphone-launchpad-cli vm leases --release
+```
+
+Launchpad のウィンドウでは、Host Setup の NAT Network にその数が表示され、Release… で管理者が承認した後に解放されます。Launchpad は、一覧に表示しているすべてのライブラリと照合します。
+
+孤立したリースとは、iOS または iPadOS のゲストのリースのうち、MAC がライブラリ内のどのマシンにも属さず、期限が切れているものです。`--release-orphans` は孤立したリースを `/var/db/dhcpd_leases` から削除し、DHCP サーバにファイルを再読み込みさせるため、root 権限が必要です。次のものには決して手を加えません。
+
+- マシン自身のリース(マシンの停止中に期限が切れたものも含む)
+- 期限が切れていないリース(MAC を置き換えたばかりの実行中のゲストのものなど)
+- ほかの仮想化アプリや、インターネット共有に接続したデバイスのリース
+
+別のライブラリにあるマシンは、そのライブラリも指定した場合にのみ数に入ります。ライブラリごとに `--library-root` を繰り返してください。ライブラリにマシンがない場合や、マシンの設定を読み取れない場合は、そこにあるリースがすべて孤立して見えてしまうため、解放の実行は拒否されます。
+
+原因:Mac の DHCP サーバは、リースの期限が切れた後も、各アドレスを割り当て先の MAC に紐付けたままにし、範囲内のほかのアドレスがすべて使われるまで別の相手には渡しません。マシンを削除したり MAC を置き換えたりすると、そのアドレスはもう誰も使わない MAC に紐付いたまま残ります。MAC が保存されるようになる前の起動でも同じことが起きています。
+
+## 固定アドレス
+
+`--ip` でゲストに固定の IPv4 アドレスを割り当てます。プレフィックスを省くと `/24` とみなされます。`--gateway` と `--dns` は省略できます。`auto` を指定すると標準に戻ります。`--ip dhcp` で固定アドレスを削除します。
+
+```sh
+vphone-cli vm config <name> --ip 192.168.65.50
+vphone-cli vm config <name> --network tunnel --ip 10.20.0.5/16 --dns 1.1.1.1
+vphone-cli vm config <name> --ip dhcp
+```
+
+アドレスがゲストに届く方法はモードによって異なります。
+
+| モード | アドレス | 適用方法 |
+| --- | --- | --- |
+| `nat` | Mac の共有 NAT ネットワーク上:通常は `192.168.65.0/24`、`--nat-peers off` のマシンでは `192.168.64.0/24`([マシン同士の通信](peers.md)をご覧ください) | vphoned がゲストのネットワーク設定に書き込みます。ゲートウェイと DNS は Mac(`192.168.65.1` または `192.168.64.1`)です。 |
+| `tunnel` | 任意のプライベートサブネット | トンネル自身の DHCP が割り当てます。ゲートウェイは DNS リゾルバも兼ね、`--gateway` で別のアドレスを指定しない限り、サブネットの最初のアドレスです。 |
+| `bridged` | 物理ネットワーク上のアドレス | vphoned がゲストに書き込みます。`--gateway` と `--dns` はそのネットワークのものを設定してください。 |
+
+> [!TIP]
+> 共有の `nat` ネットワーク上のアドレスは、Mac の DHCP サーバで予約されません。`.200` のように、DHCP がほかの仮想マシンに割り当てていそうにない、範囲の上のほうのアドレスを選んでください。
+
+`nat` モードでは、アドレスはマシンが参加する共有ネットワーク上のものでなければなりません。互いに通信するマシン(標準)の場合は 2 つ目のネットワーク(`192.168.65.0/24`)、`--nat-peers off` の場合は 1 つ目のネットワーク(`192.168.64.0/24`)です。どちらも、vmnet の `Shared_Net_Address` が変更されていればそれに従います。ほかのサブネットを使う場合は `tunnel` を使ってください。
+
+vphoned は、`vphone-vm` が接続するたびにアドレスを適用するため、Mac が関与していない間にゲスト側で変更されても元に戻されます。解除するのは自分が書き込んだ設定だけです。ゲストの「設定」アプリで手入力したアドレスは、仮想マシンが DHCP に戻ってもそのまま残ります。
+
+macOS 26 では仮想マシンに専用の NAT ネットワークを割り当てられますが、その場合、仮想マシンの停止後もサブネットが予約されたまま残り(テストでは 40 分後も予約されたままでした)、その間はそのネットワークでの起動がすべて失敗するため、vphone はこれを使いません。
+
+## 関連項目
+
+- [ネットワーク](overview.md)
+- [ポート転送](port-forwarding.md)
+- [マシン同士の通信](peers.md)
diff --git a/Documents/ja/networking/names.md b/Documents/ja/networking/names.md
new file mode 100644
index 00000000..df7c73be
--- /dev/null
+++ b/Documents/ja/networking/names.md
@@ -0,0 +1,70 @@
+# ネットワーク上の名前
+
+このページでは 2 つの名前について説明します。Mac が名前でゲストに到達できるようにする、ゲスト自身の `.local` 名と、ゲストが解決するこの Mac の `.local` 名です。
+
+## ゲストの名前(mDNS)
+
+標準ではオフです。オンにすると、名前でゲストに到達できます。
+
+```sh
+vphone-cli vm config <name> --mdns on
+ping <vm-name>.local
+```
+
+| 設定 | 効果 |
+| --- | --- |
+| `--mdns on` | ゲストが `<vm-name>.local` に応答します。仮想マシン名の英字と数字以外の文字はハイフンになります:`ipad_pro.13` は `ipad-pro-13.local` になります。 |
+| `--mdns <name>` | ゲストが、選んだ別の名前に応答します。 |
+| `--mdns off` | ゲスト本来の名前に戻ります。 |
+
+名前は `none` も含め、すべてのモードで使えます。
+
+| モード | `<name>.local` の解決先 |
+| --- | --- |
+| `nat` | 共有ネットワーク上のゲストのアドレスと、USB リンクのアドレス |
+| `bridged` | LAN 上のすべてのデバイスからはゲストの LAN アドレス、Mac からは USB リンクのアドレスも |
+| `tunnel`、`none` | ゲストの USB リンクのアドレス(Mac からのみ) |
+
+ゲストには、ネットワークカードのほかに、USB で接続した iPhone が Mac に提供するのと同じネットワークリンクがあります。これは Mac 上で `169.254` のアドレスを持つ `en` インターフェースとして表示されます。このアドレスはリンクローカルですが、Mac はこのアドレスで直接ゲストに到達できるため、`tunnel` モードでも `<name>.local` への接続はポート転送なしでゲストのサービスに届きます。
+
+知っておくべきこと:
+
+- ほかのデバイスがすでにその名前を使っている場合、mDNS はゲストの名前を変更します(`name-2`)。
+- `vm rename` は、`--mdns on` で仮想マシン名から作られた名前を変更します。手動で選んだ名前はそのまま残ります。
+- `vm stop` やウィンドウを閉じて停止した仮想マシンは、自身のアナウンスを取り消せません。Mac のリゾルバは、キャッシュされたレコードの期限が切れるまで古いアドレスを返し続けます。ホストアドレスの場合、これは 75 分(TTL 4500 秒)です。
+
+vphoned は、`vphone-vm` が接続するたびにゲストのネットワーク設定(`LocalHostName`)に名前を設定し、ゲストの mDNSResponder がすべてのリンクでそれをアナウンスします。
+
+## ゲスト内でのこの Mac の名前
+
+標準ではオンです。ゲストは、この Mac の mDNS 名(`scutil --get LocalHostName` に `.local` を付けたもの)を、ゲストが Mac に到達するためのアドレスにすぐに解決します。
+
+| モード | ゲスト内での `<Mac>.local` |
+| --- | --- |
+| `nat` | 共有ネットワーク上の Mac。通常は `192.168.65.1`(`--nat-peers off` の場合は `192.168.64.1`) |
+| `tunnel` | ゲートウェイ(標準は `192.168.127.1`)。ここへの接続は、QEMU や VirtualBox の `10.0.2.2` と同じように、Mac のループバック(`127.0.0.1`)に届きます |
+| `bridged` | ブリッジしたインターフェース上の Mac のアドレス |
+
+これを無効にするには:
+
+```sh
+vphone-cli vm config <name> --mac-name off
+```
+
+ゲストのリゾルバが返す内容と、各アドレスに接続できるかどうかを確認するには:
+
+```sh
+vphone-launchpad-cli guest rpc <name> network.resolve '{"host":"<Mac>.local","family":"ipv4","port":8000}'
+```
+
+### 必要な理由
+
+mDNS だけでは、ゲスト内での Mac の名前の IPv4 検索が失敗することがありました。ゲストは USB リンク上でも Mac の応答を受け取りますが、そこでは Mac に IPv4 アドレスがないため「そのようなレコードはない」と応答します。最初に応答したリンクで検索結果が決まるため、IPv4 アドレスを必要とするアプリは、別のリンクからの正しい応答がキャッシュされるまでエラーを受け取っていました。また、検索結果では USB リンク上の Mac の `169.254` アドレスが先頭に来ていました。iOS は `169.254.0.0/16` をプライマリインターフェース経由でルーティングするため、そのアドレスに接続する通常のソケットは、何も応答しない `en0` から送り出され、タイムアウトまで待たされることがありました。
+
+vphoned は、`/etc/hosts` の行と同じように、ゲスト自身の mDNSResponder にローカルレコードとして名前を登録します。これにより、ネットワークに問い合わせることも、キャッシュした応答を使うこともなく、IPv4 の検索にその 1 つのアドレスですぐに応答します。登録は `vphone-vm` が接続するたびに行われ、vphoned の起動時にも行われるため、再起動後にアプリが動き出す前に名前が用意されます。ゲストのシステムボリュームは読み取り専用なので、`/etc/hosts` そのものは編集されず、どのネットワークにも何もアナウンスされません。IPv6 の検索は引き続き mDNS に送られます。
+
+## 関連項目
+
+- [ネットワーク](overview.md)
+- [MAC アドレスと IP アドレス](addresses.md)
+- [トンネルモード](tunnel.md)
diff --git a/Documents/ja/networking/overview.md b/Documents/ja/networking/overview.md
new file mode 100644
index 00000000..b0bca510
--- /dev/null
+++ b/Documents/ja/networking/overview.md
@@ -0,0 +1,56 @@
+# ネットワーク
+
+各仮想マシンには 1 つのネットワークモードがあります。このページでは、モードの選び方と、実行中の仮想マシンのネットワークを切断する方法を説明します。このセクションのほかのページでは、トンネルモード、アドレス、ポート転送、名前、マシン同士の通信を扱います。
+
+## ネットワークモード
+
+| モード | ゲストがインターネットに接続する方法 | 使う場面 |
+| --- | --- | --- |
+| `nat` | Virtualization.framework に組み込まれた NAT | 標準です。Mac で VPN を使っていない場合、または VPN でゲストの通信を運ぶ必要がない場合。 |
+| `bridged` | Mac の物理インターフェースに直接つながり、そのネットワーク上に独自のアドレスを持つ | LAN 上のほかのマシンからゲストに到達できる必要がある場合。 |
+| [`tunnel`](tunnel.md) | `vphone-vm` が Mac 上で開く通常の接続を通じて | Mac の通信が VPN やプロキシアプリを経由していて、ゲストの通信もそれに従う必要がある場合。 |
+| `none` | ネットワークデバイスなし | ゲストをオフラインのままにする必要がある場合。 |
+
+モードは仮想マシンの `config.plist` に保存され、仮想マシンの起動時に読み込まれるため、変更は次回の起動から反映されます。
+
+## モードを選ぶ
+
+Launchpad では:
+
+1. マシンを停止します。
+2. `⋯` メニューまたは右クリックメニューから Settings… を選びます。
+3. Network セクションでモードを選びます。
+
+New Machine では、Advanced Options でモードを設定します。マシンを 1 台選択している場合、Settings… には Address と Port Forwarding のセクションもあります。
+
+コマンドラインでは:
+
+```sh
+vphone-cli vm config <name> --network tunnel
+# or through Launchpad
+vphone-launchpad-cli exec vm config <name> --network tunnel
+```
+
+`tunnel` を使うには、`vphone-cli vm config --help` に `tunnel` が表示される `VPhone.bundle` が必要です。古いバンドルはこの設定を拒否します。
+
+## 実行中の仮想マシンのネットワークを切断する
+
+`vm network` は実行中の仮想マシンに対して動作し、その操作は何も保存されません。
+
+```sh
+vphone-cli vm network <name> # state of the NIC
+vphone-cli vm network <name> --link down # unplug the cable
+vphone-cli vm network <name> --link up # plug it back in
+```
+
+ゲストからは、リンクが切れて再びつながったように見えます。同じリクエストは、`vphone.sock` でも `{"t":"network"}` に `"link":"down"` または `"link":"up"` を付けて送れます。
+
+> [!NOTE]
+> 実行中の仮想マシンを別のネットワークに移すことはできません。Virtualization はその変更を受け付けた後、内部エラーで仮想マシンを停止してしまうため、`vm network` は仮想マシンが起動時に使っていたネットワークにつなぎ直すことしかできません。モードを変更するには、`vm config` を使って仮想マシンを再起動してください。
+
+## 関連項目
+
+- [トンネルモード](tunnel.md):VPN やプロキシアプリを使っている Mac
+- [MAC アドレスと IP アドレス](addresses.md):保存された MAC、古い MAC が保持するリース、固定アドレス
+- [ポート転送](port-forwarding.md):Mac のポートをゲストに転送する
+- [ネットワーク上の名前](names.md)と[マシン同士の通信](peers.md)
diff --git a/Documents/ja/networking/peers.md b/Documents/ja/networking/peers.md
new file mode 100644
index 00000000..b55fa8cc
--- /dev/null
+++ b/Documents/ja/networking/peers.md
@@ -0,0 +1,33 @@
+# マシン同士の通信
+
+1 台の Mac 上の `nat` マシンは、Bonjour も含めて互いに直接通信できます。仮想 Apple Watch は、この方法で仮想 iPhone とペアリングします。このページでは、1 台のマシンを切り離す方法を説明します。
+
+## マシンを切り離す
+
+```sh
+vphone-cli vm config <name> --nat-peers off # isolate this guest again
+vphone-cli vm config <name> --nat-peers on # the default
+```
+
+Launchpad では、マシンの Network 設定にある「Reach other NAT machines」です。変更は次回の起動から反映されます。
+
+切り離したゲストは Mac とインターネットには接続できますが、ほかの仮想マシンには接続できません。切り離しは各マシン自身の接続の設定なので、オプトアウトしたマシンは、ほかのマシンの設定にかかわらず切り離されたままです。
+
+## マシンが参加するネットワーク
+
+| 設定 | 共有ネットワーク | Mac のアドレス |
+| --- | --- | --- |
+| `--nat-peers on`(標準) | `192.168.65.0/24` | `192.168.65.1` |
+| `--nat-peers off` | `192.168.64.0/24` | `192.168.64.1` |
+
+[固定アドレス](addresses.md)(`--ip`)は、マシンが参加するネットワーク上のものでなければなりません。固定アドレスが 1 つ目のネットワーク(`192.168.64.0/24`)上にあるマシンは、ほかのマシンとの通信を求めない限り切り離されたままで、求める場合は 2 つ目のネットワーク上のアドレスが必要です。
+
+## 背景
+
+標準では、Virtualization.framework は Mac の共有ネットワーク上で各 `nat` ゲストをほかのゲストから切り離します。vphone はこの切り離しをオフにし、vmnet は互いに通信するマシンを 2 つ目の共有ネットワーク(1 つ目の次のブロック)に置きます。このスイッチは Virtualization.framework の非公開のものです。これがないバージョンでは、すべてのゲストが切り離されたままになり、仮想マシンの起動時にその旨が表示されます。
+
+## 関連項目
+
+- [ネットワーク](overview.md)
+- [MAC アドレスと IP アドレス](addresses.md)
+- [ネットワーク上の名前](names.md)
diff --git a/Documents/ja/networking/port-forwarding.md b/Documents/ja/networking/port-forwarding.md
new file mode 100644
index 00000000..dc63d95e
--- /dev/null
+++ b/Documents/ja/networking/port-forwarding.md
@@ -0,0 +1,40 @@
+# ポート転送
+
+`nat` モードと `tunnel` モードで Mac のポートをゲストに転送するには、`--forward` を使います。`bridged` ではゲストが独自のアドレスで LAN に参加するため、転送は必要ありません。
+
+## 転送の追加と削除
+
+```sh
+vphone-cli vm config <name> --forward tcp:8022:22
+vphone-cli vm config <name> --forward udp:0.0.0.0:5353:53
+vphone-cli vm config <name> --remove-forward 8022
+vphone-cli vm config <name> --clear-forwards
+```
+
+形式は次のとおりです。
+
+```text
+[tcp|udp:][host-address:]host-port:guest-port
+```
+
+| 要素 | 意味 |
+| --- | --- |
+| `tcp` または `udp` | プロトコル |
+| `host-address` | Mac 上で転送がリッスンするアドレス。標準は `127.0.0.1` です。`0.0.0.0` にすると LAN 上のほかのデバイスから到達できるようになります。 |
+| `host-port` | Mac 上のポート |
+| `guest-port` | ゲスト内のポート |
+
+複数のポートを転送するには、`--forward` を繰り返します。Launchpad では、マシンの Settings… に Port Forwarding セクションがあります。
+
+## 転送の動作
+
+- `vphone-vm` は、仮想マシンの起動時にリスナーを開き、停止時に閉じます。
+- `nat` モードでは、ゲストのアドレス([固定アドレス](addresses.md)、または vphoned が報告するアドレス)に接続します。
+- `tunnel` モードでは、接続はゲートウェイから来たものとしてゲストに届きます。
+- Mac ですでに使われているポートは仮想マシンのログに記録されてスキップされ、ほかの転送は引き続き動作します。
+
+## 関連項目
+
+- [ネットワーク](overview.md)
+- [トンネルモード](tunnel.md)
+- [MAC アドレスと IP アドレス](addresses.md)
diff --git a/Documents/ja/networking/tunnel.md b/Documents/ja/networking/tunnel.md
new file mode 100644
index 00000000..e7d4ce9e
--- /dev/null
+++ b/Documents/ja/networking/tunnel.md
@@ -0,0 +1,66 @@
+# トンネルモード
+
+Mac の通信が VPN やプロキシアプリを経由していて、ゲストの通信も同じ経路を通る必要がある場合は、`tunnel` モードを使います。`nat` と `bridged` では、ゲストのパケットは VPN を経由しません。
+
+## 有効にする
+
+マシンを停止してから、次を実行します。
+
+```sh
+vphone-cli vm config <name> --network tunnel
+```
+
+Launchpad では、マシンの Settings… の Network セクションで `tunnel` を選びます。バンドルの `vphone-cli vm config --help` に `tunnel` が表示される必要があります。古いバンドルはこの設定を拒否します。
+
+## 動作を確認する
+
+1. マシンを起動し、起動が完了するまで待ちます。
+2. ゲストのアドレスを読み取ります。
+
+ ```sh
+ vphone-launchpad-cli guest rpc <name> device.network
+ ```
+
+ `en0` に `192.168.127.3` が表示されるはずです。`fe80::` のアドレスしか表示されない場合は、DHCP がまだ完了していません。数秒待ってからもう一度試してください。
+3. ゲストでページを開きます。
+
+ ```sh
+ vphone-launchpad-cli guest rpc <name> apps.open_url '{"url":"https://example.com"}'
+ ```
+
+4. Mac で、接続が `vphone-vm` に属し、VPN のアドレスを使っていることを確認します。
+
+ ```sh
+ lsof -nP -a -i -p "$(pgrep -f 'vphone-vm.*<name>')"
+ ```
+
+## ゲストから見える内容
+
+| 項目 | 値 |
+| --- | --- |
+| ゲストのアドレス | DHCP による `192.168.127.3/24`、または[固定アドレス](addresses.md) |
+| ゲートウェイと DNS | `192.168.127.1`、または固定アドレスのサブネットの最初のアドレス |
+| MTU | 1500 |
+| DNS | `192.168.127.1` への問い合わせは Mac のリゾルバに送られます |
+| ゲートウェイへのその他の接続 | Mac のループバック `127.0.0.1`(TCP と UDP) |
+
+プロキシアプリでは、ゲストはマシンの名前が付いた独立したクライアントとして表示され、アプリのルールがほかのアプリと同じように適用されます。
+
+## 制限
+
+- **IPv4 のみ。** ゲストには IPv6 アドレスが割り当てられず、IPv6 の通信は破棄されます。
+- **転送したポートを除き、外向きのみ。** [ポート転送](port-forwarding.md)で指定したポート以外では、Mac や LAN からこのネットワークを通じてゲストに到達することはできません。USB 経由のアクセス(`iproxy`、`ideviceinstaller`)と `vphone.sock` はゲストのネットワークを使わないため、引き続き動作します。`.local` 名でも USB リンク経由でゲストに到達できます。[ネットワーク上の名前](names.md)をご覧ください。
+- **ping はゲートウェイにしか届きません。** インターネットへの ICMP は転送されないため、TCP と UDP が動作していても、ゲストでの `ping 1.1.1.1` は失敗します。
+- **スループットは `vphone-vm` によって制限されます。** すべてのパケットはこのプロセスで処理されます。ダウンロードやビデオは問題なく動作しますが、VPN が関係しない場合は `nat` のほうが高速です。
+
+## 仕組み
+
+VPN が Mac のデフォルトルートを握っている場合(WireGuard、Cloudflare WARP、または Surge や Clash などの TUN モードのプロキシアプリ)、`nat` と `bridged` が物理インターフェースから送り出すパケットは VPN を経由しません。暗号化されないまま送られるか、まったく送られません。
+
+`tunnel` モードでは、ゲストのネットワークカードは `vphone-vm` の内部で実装されます。ゲートウェイとして DHCP、ARP、ping に応答し、ゲストの各 TCP 接続と UDP フローを Mac 上の通常のソケットに変換します。それらのソケットはほかのアプリと同じく Mac のルーティングテーブルに従うため、VPN がそれらを運びます。root 権限も、新しいネットワークインターフェースも、Mac のネットワーク設定の変更も必要ありません。
+
+## 関連項目
+
+- [ネットワーク](overview.md)
+- [MAC アドレスと IP アドレス](addresses.md)
+- [ポート転送](port-forwarding.md)
diff --git a/Documents/ja/storage/library-and-backups.md b/Documents/ja/storage/library-and-backups.md
new file mode 100644
index 00000000..f1842364
--- /dev/null
+++ b/Documents/ja/storage/library-and-backups.md
@@ -0,0 +1,69 @@
+# ライブラリ、ファームウェア、バックアップ
+
+vphone がマシンとダウンロードしたファームウェアを保存する場所、それらを移動する方法、マシンをコピー、バックアップ、復元する方法を説明します。ディスク容量の計画を立てる場合、ライブラリを移動する場合、マシンのコピーがもう 1 つ必要な場合にご覧ください。
+
+## バックアップ、コピー、復元
+
+```sh
+vphone-cli vm list
+vphone-cli vm info myphone
+vphone-cli vm clone myphone copy # backup: same identity
+vphone-cli vm clone myphone second --new-identity # a second device
+vphone-cli vm export myphone --out myphone.tzst
+vphone-cli vm import myphone.tzst --name restored
+```
+
+`vm clone` は停止中のマシンをコピーします。使える場合は APFS のコピーオンライトを使います。コピー元が実行中の場合は拒否されます。
+
+| 複製 | アイデンティティ | 用途 |
+| --- | --- | --- |
+| 通常の `vm clone` | マシン識別子と MAC アドレスが同じ | バックアップ。元のマシンと同時には実行できません。 |
+| `vm clone --new-identity` | 新しいマシン識別子(ECID)と、それに伴う新しい UDID。MAC アドレスは初回起動時に新しくなります | 元のマシンと同時に実行できる 2 台目のデバイス |
+
+`--new-identity` で作ったコピーは:
+
+- 固定の IPv4 アドレス、ポート転送、手動で選んだ mDNS 名を消去します。元のマシンのものと衝突するためです。`--mdns on` で元のマシンの名前から作られた mDNS 名は、名前の変更時と同じく新しい名前に追従します。必要であれば `vm config` で新しく設定してください。
+- 元のマシンのデータ、アプリ、設定を引き継ぎます。復元は必要ありません。
+- `ideviceinstaller` などの lockdown ツールを使う前に、ロックを解除してこの Mac をもう一度信頼する必要があります。
+- APFS 上では元のマシンとディスクブロックを共有し、変更した分だけを保持します。最初の数回の起動後で約 0.35 GB です。ただし、`du` と Finder はそれぞれのフルサイズを表示します。
+
+> [!WARNING]
+> マシン間で `SEPStorage`、`nvram.bin`、ディスクイメージを入れ替えないでください。これらは 1 回の復元で一緒に作られたもので、SEP ストレージがディスクと一致しないゲストは起動時にパニックします。
+
+## ファイルの保存場所
+
+| 標準のパス | 内容 |
+| --- | --- |
+| `~/.vphone/machines/<name>/` | 1 台の仮想マシン。ディスク、`config.plist`、パッチの作業ファイルを含みます |
+| `~/.vphone/ipsws/` | リモートから取得したソース IPSW。すべての仮想マシンで共有されます。ローカルの IPSW はその場で読み取られます |
+| `~/.vphone/gpu-drivers/<version>_<build>/` | cloudOS から取り出した GPU ドライバのバンドル。すべての仮想マシンで共有されます |
+| `~/.vphone/kernelcache/` | vphone600 のコンポーネントを含まない cloudOS リリース用の kernelcache ミックス、その準備用ボリューム、ドナーから展開したもの |
+
+これらを移動するには:
+
+| 設定 | 移動されるもの |
+| --- | --- |
+| `VPHONE_ROOT` | `~/.vphone` のデータルート全体:マシンライブラリとキャッシュ |
+| `VPHONE_LIBRARY_ROOT` | マシンライブラリだけ。`VPHONE_ROOT` より優先されます |
+| `vm create` と `fw prepare` の `--ipsw-cache <dir>` | IPSW キャッシュだけ |
+
+## IPSW キャッシュとダウンロード
+
+ダウンロードした IPSW は削除するまでキャッシュに残るため、同じ URL から 2 台目のマシンを作るときは何もダウンロードされません。Launchpad では **File > Downloaded IPSWs…** で削除できます。
+
+準備した復元ツリーは、`--keep-artifacts` を指定しない限り、`vm create` が成功した後に削除されます。以前のビルドで準備したマシンには `.ipsw-cache/` ディレクトリが残っていることがあります。これは削除しても問題なく、`vm export` にも含まれません。
+
+リモートの IPSW は、Apple の CDN のようにサーバが HTTP の範囲リクエストに応答する場合、4 つの接続で同時にダウンロードされます。各接続は 32 MB のセグメントを順に取得し、途切れたセグメントは止まった位置から再開します。`fw prepare` の `--download-connections <n>` で接続数を 1〜16 の範囲で設定できます。1 にすると IPSW は単一のストリームでダウンロードされます。範囲リクエストを無視するサーバの場合も同じになります。
+
+## ディスク容量とメモリ
+
+リソースを多く使う作成処理は、1 つずつ実行してください。IPSW と一時的な復元ツリーはかなりのディスク容量を使い、大きなキャッシュへのパッチ適用には多くのメモリが必要になることがあります。2 台目のマシンを作り始める前に、空き容量を確認してください。
+
+Launchpad は、該当する場合、CFW の作業ファイルをライブラリがマウントされている外部ボリュームに置きます。単体の `vphone-cli cfw install` の標準は `/private/var/tmp` で、root 所有の非公開ディレクトリを指定する `--work-parent` を受け付けます。
+
+## 関連項目
+
+- [スナップショット](snapshots.md)
+- [テンプレート](templates.md)
+- [仮想マシン間でのディスク容量の共有](sharing-disk-space.md)
+- [マシンの作成と実行](../machines/create-and-run.md)
diff --git a/Documents/ja/storage/many-machines.md b/Documents/ja/storage/many-machines.md
new file mode 100644
index 00000000..15251d99
--- /dev/null
+++ b/Documents/ja/storage/many-machines.md
@@ -0,0 +1,61 @@
+# 複数マシンの一括作成
+
+`vm create-bulk` は、plist に記述されたすべてのマシンを順に作成します。1 つのファイルから実験環境や CI 用のマシン群を準備するときに使います。
+
+## 実行する
+
+```sh
+vphone-cli vm create-bulk list.plist --dry-run # print each machine's vm create command
+vphone-cli vm create-bulk list.plist
+```
+
+`vm create` と同じく、マシンのビルドが必要な場合は `sudo` で実行してください。
+
+## リストを書く
+
+```xml
+<dict>
+ <key>version</key> <integer>1</integer>
+ <key>defaults</key>
+ <dict>
+ <key>library-root</key> <string>~/vphone-lab</string>
+ <key>iphone-version</key> <string>26.1</string>
+ <key>preset</key> <string>presets/lab.plist</string>
+ <key>cpu</key> <integer>4</integer>
+ </dict>
+ <key>machines</key>
+ <array>
+ <dict><key>name</key> <string>ci-1</string></dict>
+ <dict><key>name</key> <string>ci-2</string></dict>
+ <dict>
+ <key>name</key> <string>fuzz</string>
+ <key>iphone-build</key> <string>23F77</string>
+ <key>iphone-version</key> <false/>
+ <key>no-template</key> <true/>
+ </dict>
+ </array>
+</dict>
+```
+
+- 各キーは `vm create` のオプションの長い名前で、値を伴います。値は文字列または整数、フラグには `true`、`keep-apps` には配列を使います。
+- `defaults` はすべてのマシンに適用されます。マシン自身のキーが優先され、`false` を指定すると `defaults` の値を消去します。
+- 相対パスは plist のあるフォルダを基準に解決されます。
+- `library-root` はマシンを別のライブラリに置きます。コマンドラインの `-l` がこれより優先されます。
+- 何も入力を求められないように、すべてのマシンでファームウェア(`iphone-version`、`iphone-build`、または `iphone-source` と `cloudos-source`)か `template` を指定する必要があります。
+
+## 実行時の動作
+
+最初のマシンを作る前に、すべてのマシンが `vm create` と同じ方法でチェックされます。マシンは順に作成されるため、テンプレートのキーが同じマシンは、最初のマシンが作ったテンプレートから複製されます。最初の失敗で実行が止まります。
+
+すでにある名前はエラーになります。この動作は次の 2 つのフラグで変えられますが、両方を同時には指定できません。
+
+| フラグ | 効果 |
+| --- | --- |
+| `--skip-existing` | 名前がすでにあるマシンを飛ばします。途中で止まった実行を、残りのマシンについてやり直せます。失敗したマシンは止まった状態のまま残るため、先に削除してください。削除しないと、そのマシンも飛ばされます。 |
+| `--force-override` | そのマシンを作成する直前に、同名の仮想マシンを削除します。実行中の仮想マシンや、仮想マシンではないフォルダは拒否します。 |
+
+## 関連項目
+
+- [テンプレート](templates.md)
+- [テンプレートの作成と検索](template-building.md)
+- [マシンの作成と実行](../machines/create-and-run.md)
diff --git a/Documents/ja/storage/shader-cache.md b/Documents/ja/storage/shader-cache.md
new file mode 100644
index 00000000..1dfdb746
--- /dev/null
+++ b/Documents/ja/storage/shader-cache.md
@@ -0,0 +1,64 @@
+# 永続シェーダキャッシュ
+
+マシンはコンパイル済みの GPU シェーダを起動をまたいで保持するため、アニメーションがもたつくのは、最初の数回の実行でシェーダをコンパイルしている間だけです。このページでは、既存のマシンでキャッシュを有効にする方法と、キャッシュをリセットする方法を説明します。
+
+Standard プリセットで作成した新しいマシンでは、Task3 カーネルパッチとゲストの Metal キャッシュの再利用が自動的に有効になります。ホストはキャッシュを `<machine>/ShaderCache`(例:`~/.vphone/machines/Lychee/ShaderCache`)に保存します。実行ファイルが変わると、ホストのキャッシュのアイデンティティも新しくなります。
+
+## 既存のマシンで有効にする
+
+この機能を含む Core Bundle をインストールし、停止中のマシンをそのバンドルに紐付けます。その後、ゲスト環境とカーネルを更新します。どちらの更新でもゲストのデータは保持され、復元も `fw patch` も必要ありません。
+
+### Launchpad で
+
+1. マシンのアクションメニューから **Update Guest Environment** を選びます。
+2. **Patches** インスペクタで **Update Kernel** を選びます。
+
+Standard では **GPU Task3 shader cache** が自動的に選択されるようになりました。マシンごとに明示的にオフにした設定は保持されます。パッチのチェックを外していた場合は、先にエディタで有効にしてください。
+
+### Launchpad CLI で
+
+```sh
+# Replace <version> with the installed Core Bundle version from bundle list.
+vphone-launchpad-cli vm stop Lychee
+vphone-launchpad-cli vm set-bundle Lychee <version> --update-environment
+vphone-launchpad-cli cfw update-kernel Lychee
+vphone-launchpad-cli vm start Lychee --wait
+```
+
+- `--update-environment` は、ゲストライブラリとキャッシュ再利用のマーカーを配置し直します。
+- `cfw update-kernel` は、`FirmwareOriginals` にある未変更のカーネルに現在の選択でパッチを適用し直し、Preboot の kernelcache を置き換えます。
+
+Core Bundle の紐付けを変えるだけでは、インストールされたカーネルは更新されません。
+
+### vphone-cli だけで
+
+マシンの電源を切った状態で、新しいバンドルのコマンドを root 権限で実行します。
+
+```sh
+sudo vphone-cli cfw update-environment Lychee
+sudo vphone-cli cfw update-kernel Lychee
+```
+
+`vphone-cli fw patches Lychee` で保留中のパッチを確認できます。どちらの更新コマンドも、ほかに保留中のゲストやカーネルの変更も含め、マシンの現在の選択を適用します。
+
+### 未変更のカーネルがない古いマシン
+
+`FirmwareOriginals` に未変更のカーネルがないマシンでは、先に新しいバンドルで `fw prepare` と `fw patch` を実行し、代わりに使われる復元ツリーに更新後のカーネルが含まれるようにします。その後 `cfw update-kernel` を実行します。`restore` は実行しないでください。
+
+## ホストのキャッシュをリセットする
+
+マシンを停止してから、その `ShaderCache` ディレクトリを削除します。次回の起動で、新しいホストキャッシュが作られます。
+
+ゲストの Metal キャッシュは `Disk.img` 内の別のファイルなので、ホストのキャッシュを消去しても、初回実行時のもたつきがすべて再現されるとは限りません。
+
+## 制限
+
+- Task3 は cloudOS 26.4 のカーネルにのみ適用され、tvOS のプリセットでは無効です。
+- macOS 27 より前のホストでは、ゲストはホスト自身の最大バージョンでネゴシエーションし、そのバージョンの機能を使うため、ホストのキャッシュは起動ごとのものになります。
+- 実行時の検証は、macOS 27.0.1、cloudOS 26.4、iOS 27.0.1 と 26.6.2 のゲストで行いました。古いホストはフレームワークのコードから確認したもので、実際には実行していません。
+
+## 関連項目
+
+- [Core Bundle](../launchpad/core-bundles.md)
+- [Launchpad CLI](../launchpad/launchpad-cli.md)
+- [ライブラリ、ファームウェア、バックアップ](library-and-backups.md)
diff --git a/Documents/ja/storage/sharing-disk-space.md b/Documents/ja/storage/sharing-disk-space.md
new file mode 100644
index 00000000..486ef42b
--- /dev/null
+++ b/Documents/ja/storage/sharing-disk-space.md
@@ -0,0 +1,50 @@
+# 仮想マシン間でのディスク容量の共有
+
+`vm rebase` を使うと、停止中の仮想マシンが、ほかの仮想マシンやテンプレートと同一のディスクブロックを 1 つだけ保存するようになります。テンプレートを使わずに復元したマシンや読み込んだマシンで、ディスク容量を取り戻すときに使います。
+
+同じ IPSW から別々に復元した 2 台の仮想マシンは、ディスクイメージの多くが同じでも、ディスク上では何も共有しません。iOS 27.0 の iPhone 2 台では、約 20 GB のデータのうち約 8.6 GB が同じ位置にある同一のバイトで、そのほとんどがシステムボリュームです。
+
+## 仮想マシンをリベースする
+
+1. 両方のマシンを停止します。両方が同じ APFS ボリューム上にある必要があります。
+2. リベースで節約できる容量を確認します。
+
+ ```sh
+ vphone-cli vm rebase second --onto first --dry-run
+ ```
+
+3. 仮想マシンまたはテンプレートを基準にリベースします。
+
+ ```sh
+ vphone-cli vm rebase second --onto first
+ vphone-cli vm rebase second --onto 3f2a91c0d4e7
+ ```
+
+`--onto` には、仮想マシンの名前か、`vm template list` に表示されるテンプレート識別子(または一意に決まるその先頭部分)を指定します。名前が両方に一致する場合は仮想マシンが優先されます。`--dry-run` は何も書き込まずに、共有される量と書き込まれる量を報告します。
+
+古いイメージが解放されるまで、ボリュームには書き込まれるブロック分の空き容量が必要です。
+
+## 処理の内容
+
+リベースは、基準となるイメージの APFS クローンから `second` のディスクイメージを作り直し、異なるブロックだけを書き込みます。イメージを置き換える前にすべてのバイトを元のイメージと比較するため、ゲストからはまったく同じディスクに見えます。
+
+変わるのはディスクイメージだけです。`SEPStorage`、`nvram.bin`、`config.plist`、デバイスのアイデンティティはそのままです。テンプレートを基準にリベースしてもテンプレートは変わらず、仮想マシンがそのテンプレートの複製になるわけでもありません。`vm template show` にも表示されません。
+
+## 結果の読み方
+
+節約される容量は **newly shared** の数値です。同一でもすでにディスク上で同じブロックになっているバイトは **already shared** として報告され、それをリベースしても何も解放されません。
+
+`vm create` で 1 つのテンプレートから作った仮想マシンは、すでにそのブロックを共有しているため、互いに、またはそのテンプレートを基準にリベースしてもほとんど解放されません。コマンドは比較の前にその旨を伝え、節約量が 0.1 GB 未満の場合にも再度伝えます。リベースする価値があるのは、テンプレートなしで復元した仮想マシン(`--no-template`)や読み込んだ仮想マシンです。
+
+## 知っておくべきこと
+
+- 容量が戻るのは、古いイメージのブロックをほかに何も保持していない場合だけです。その仮想マシンのスナップショットや、そこから作った複製はブロックを保持します。先にそれらを削除しないと、節約は見込めません。
+- `du` と Finder は、引き続き各イメージをフルサイズで数えます。ボリュームの空き容量(`df`)が正確な目安です。
+- どちらかの仮想マシンがディスクに書き込むと、2 つのイメージは再び離れていきます。テンプレートのように一度も起動しない基準が最適で、後でもう一度リベースすると離れた分を取り戻せます。
+- 中断されたリベースは仮想マシンを変更しませんが、その中に隠しフォルダ `.rebase-*` が残ることがあります。そのフォルダは削除してください。
+
+## 関連項目
+
+- [テンプレート](templates.md)
+- [スナップショット](snapshots.md)
+- [ライブラリ、ファームウェア、バックアップ](library-and-backups.md)
diff --git a/Documents/ja/storage/snapshots.md b/Documents/ja/storage/snapshots.md
new file mode 100644
index 00000000..dbe28703
--- /dev/null
+++ b/Documents/ja/storage/snapshots.md
@@ -0,0 +1,65 @@
+# スナップショット
+
+スナップショットは、停止中のマシンのディスクと起動状態を保存し、後でその状態に戻せるようにするものです。クリーンインストールの直後にスナップショットを作成しておけば、ゲストで破壊的な操作を試した後に元に戻せます。
+
+## 作成、一覧表示、復帰、削除
+
+1. マシンを停止します:`vphone-cli vm stop myphone`、またはウィンドウから閉じます。
+2. スナップショットを作成してから、ゲストで作業します。保存した状態に戻したくなったら、マシンをもう一度停止して復帰します。
+
+```sh
+vphone-cli vm snapshot create myphone clean --note "fresh install"
+vphone-cli vm snapshot list myphone
+vphone-cli vm snapshot revert myphone clean
+vphone-cli vm snapshot delete myphone clean
+```
+
+- `revert` と `delete` は、何かを変更する前に確認を求めます。`--force` を指定すると確認を省きます。
+- 復帰してもスナップショットは残るため、何度でもその状態に戻れます。
+- `list --json` は `{"name", "created", "note"}` オブジェクトの配列を古い順に出力します。`created` は ISO 8601 形式で、メモがない場合 `note` は省かれます。
+- `list` と `delete` はマシンの実行中でも使えます。どちらも実行中のファイルには触れません。
+
+## 作成や復帰が拒否される場合
+
+`create` と `revert` は、マシンの実行中、またはディスクイメージ、`SEPStorage`、`nvram.bin` をいずれかのプロセスが開いている間は拒否されます。拒否のメッセージには、それらを開いている各プロセスの名前が表示されます。そのどれもマシンを実行しているものではない場合(バックアップツール、Spotlight など)はその旨が表示され、そのプロセスがファイルを閉じれば再試行は成功します。
+
+`create` は、マシンが APFS ボリューム上にない場合にも拒否されます。数十 GB になることもあるディスクイメージをコピーしないようにするためです。
+
+`Snapshot.plist` に 3 つの状態ファイルがすべて記載されていない、またはスナップショットに含まれないファイルが記載されているスナップショットは、何かが変更される前に破損として拒否されます。
+
+復帰は、すべて成功するか何も変わらないかのどちらかです。途中で失敗した場合は、マシン自身のファイルを元に戻してエラーを報告するため、マシンは元の状態のままです。まれに元に戻す処理も失敗した場合はエラーにその旨が表示されるので、マシンを起動する前にもう一度スナップショットに復帰してください。
+
+## スナップショットに含まれるもの
+
+| 保存されるもの | 理由 |
+| --- | --- |
+| ディスクイメージ(`Disk.img`) | ゲストのシステムとデータ |
+| `SEPStorage`、`nvram.bin` | Secure Enclave の状態とブートチェーンの NVRAM。ディスクと一致している必要があります |
+| `PatchReceipt.plist` | ゲストで有効になっているパッチ |
+| `restore-info.json` | ディスク上の iOS のバージョンと、`cfw install` が完了したかどうか |
+
+ディスク、`SEPStorage`、`nvram.bin` は常に一緒に扱われます。Secure Enclave のリプレイ防止カウンタは `SEPStorage` にあり、ディスクにはそれに対応する状態が保存されています。ある時点のディスクと別の時点の `SEPStorage` を組み合わせると、次回の起動時に SEP がパニックします。
+
+`PatchReceipt.plist` と `restore-info.json` は、存在する場合に保存されます。スナップショットの作成時に存在しなかったファイルは、復帰時に削除されます。そのため、記録は後のインストールではなく復帰したディスクの内容を表します。
+
+保存されず、復帰しても変わらないもの:
+
+- `config.plist`:デバイスのアイデンティティ、CPU、メモリ、ネットワーク、その他の設定。`vm config` でいつでも変更でき、復帰してもその変更は元に戻りません。
+- パッチの選択(`PatchSelection.plist`)、復元ツリー、`FirmwareOriginals/`、ROM。これらはゲストの状態ではなく、Mac 側の入力です。
+- `launchpad.json`。Launchpad は自身のコピーをスナップショットのフォルダに保存し、自分で元に戻します。CLI はスナップショットのフォルダにある追加のファイルには手を加えず、スナップショットと一緒に削除します。
+
+## ディスク容量
+
+スナップショットは APFS クローンとして `<vm>/Snapshots/<name>/` に保存されます。作成は一瞬で、容量も使いません。マシンとそのスナップショットは、ゲストが書き込むまですべてのブロックを共有し、書き込まれた後も変更されたブロックだけが新たに容量を使います。`du` と Finder は各スナップショットをディスクのフルサイズで数えるため、実際の使用量より多く表示されます。ボリュームの空き容量が正確な目安です。
+
+スナップショットは、作成時のディスクブロックを保持します。そのマシンのスナップショットが古いブロックを保持している間は、`vm rebase` を実行しても何も解放されません。[仮想マシン間でのディスク容量の共有](sharing-disk-space.md)をご覧ください。
+
+## 複製、書き出し、名前の変更
+
+`vm clone` と `vm export` はスナップショットを含みません。複製したマシンや読み込んだマシンは、スナップショットがない状態から始まります。マシンを削除したり名前を変更したりすると、そのスナップショットも一緒に削除または移動されます。
+
+## 関連項目
+
+- [ライブラリ、ファームウェア、バックアップ](library-and-backups.md)
+- [仮想マシン間でのディスク容量の共有](sharing-disk-space.md)
+- [トラブルシューティング](../help/troubleshooting.md)
diff --git a/Documents/ja/storage/template-building.md b/Documents/ja/storage/template-building.md
new file mode 100644
index 00000000..1b5ace3c
--- /dev/null
+++ b/Documents/ja/storage/template-building.md
@@ -0,0 +1,118 @@
+# テンプレートの作成と検索
+
+仮想マシンを手動でテンプレートとして仕上げる方法、`vm create` がどのテンプレートを使うかを調べる方法、Launchpad がテンプレートを作る方法を説明します。テンプレートとは何か、そのキーに何が含まれるかについては、先に[テンプレート](templates.md)をお読みください。
+
+## 仮想マシンをテンプレートとして仕上げる
+
+作成した直後の仮想マシンをテンプレートにするには、停止して削減し、セットアップ起動を行ってから adopt します。Launchpad がテンプレートを作る必要があるときに行う処理と同じです。
+
+```sh
+vphone-cli vm stop phone-src
+vphone-cli vm template trim phone-src --tier standard # offline, no root; frees nothing until the setup boot
+vphone-cli vm template setup phone-src # headless; --window to watch, slimming switches as for vm create
+vphone-cli vm template adopt phone-src --iphone-source … --cloudos-source … # key from its records; the sources are recorded
+vphone-cli vm create phone-d --template <id> --skip-first-boot
+```
+
+### vm template setup
+
+- 実行中の仮想マシンと凍結されたテンプレートは拒否します。
+- 自身では何も削減しません。`vm template trim` が記録した段階を引き継ぎ、別の段階を指定する `--trim` は拒否します。
+- 仮想マシンでは、vphoned が削除しないアプリを報告し、それを記録する手順から除くため、adopt したキーには実際に行われたことが記載されます。
+- `--strict` を指定すると、代わりに失敗します。何も記録されず、セットアップ起動をやり直せます。同じスイッチで `vm template find` が示したキーで、`--expect` を付けて仮想マシンを adopt する場合に使います。
+- `vm template list` に表示される `.building-…` という名前(セットアップ起動に失敗した `vm create`)を指定すると、作成処理をそのキーに合わせて設定し(これで軽量化の内容が決まります)、オフラインでの削減の前に止まっていた場合は先にそれを実行し、成功すると凍結します。
+
+### vm template adopt
+
+| オプション | 効果 |
+| --- | --- |
+| `--iphone-source`、`--cloudos-source` | テンプレートを作る `vm create` と同じく、仮想マシンの作成元の IPSW を `Template.plist` に記録します。 |
+| `--json` | `vm template show --json` と同じ形式で新しいテンプレートを出力します。 |
+| `--expect <id>` | 仮想マシンの記録から求められるテンプレート識別子が `<id>`(仮想マシンの作成時のオプションで `vm template find` が表示した `id`)でない限り、拒否して仮想マシンをそのままにします。 |
+
+後でテンプレートを再び見つける必要がある場合は、必ず `--expect` を使ってください。指定しないと、セットアップ起動が不十分だった仮想マシン(削除できないアプリがあった場合など)が別のキーで保存され、同じオプションでの以降の `vm create` がすべてそれを見つけられず、別のテンプレートを作ってしまいます。
+
+期待されるキーを求められる場合、拒否のメッセージには異なるフィールドが表示されます。ライブラリ内のテンプレートや作成処理がそのキーを持っている場合、または軽量化の内容だけが異なる場合に求められます。それ以外の場合は、比較のために仮想マシン自身のキーを表示します。`--json` を指定すると拒否の内容も stdout に出力され、コマンドは終了ステータス 1 で終了します。
+
+```text
+{"adopted": false, "error": "unexpected_template", "id": …, "expected": …, "differences": […], …}
+```
+
+## テンプレートを検索する
+
+`vm template find` は、同じオプションの `vm create` がどのテンプレートから複製するかを、ダウンロード、復元、変更を一切行わずに答えます。
+
+```sh
+vphone-cli vm template find --iphone-source … --cloudos-source … [--device …] [--preset …] [--disk-size …] [--block <id>] [--allow <id>] [slimming switches] --json
+```
+
+キーは `vm create` と同じ方法で求めます。ビルドは、IPSW がローカルのファイルであるか、すでに IPSW キャッシュにある場合はその IPSW から、それ以外の場合は同じ 2 つのソースが記録されたテンプレートから求めます。そのため、IPSW を削除した後でも(ローカルのものも含め)キーを求められます。`--block` と `--allow` は、`fw set-patches` が記録するのと同じパッチごとの上書き設定です。
+
+| JSON のフィールド | 意味 |
+| --- | --- |
+| `resolved` | キーを求められたかどうか |
+| `resolvedBy` | `ipsw` または `template` |
+| `id` | テンプレート識別子 |
+| `summary` | キーの概要 |
+| `key` | キー全体 |
+| `template` | 一致するテンプレート。`vm template show --json` と同じ形式で、最新のものか古くなったものかを問いません |
+| `usable` | 存在し、最新であるかどうか |
+| `building` | 作成処理がそのビルドロックを保持しているかどうか |
+| `reason` | キーを求められなかった場合の理由 |
+
+## Launchpad で
+
+Launchpad 2.9 以降は、標準でテンプレートからマシンを作成します。
+
+### New Machine
+
+New Machine は短いページで開きます:名前、ファームウェアカタログから選ぶデバイスと iOS のバージョン、**Slim System** スイッチ。その下の行にそれ以外の設定の概要が表示され、そこから **Advanced Options** を開けます。Advanced Options は次の 4 つのページです。
+
+- ハードウェア
+- テンプレートとその構成要素:削減の段階と残す言語、サービスプロファイル、削除するシステムアプリ
+- Core Bundle、カスタム IPSW、パッチ
+- 保存場所、ネットワーク、復元のオプション
+
+この行には、標準と異なる設定の数と、**Create** を妨げている項目が表示されます。**Create from a template** をオフにすると、`--no-template` と同じく、軽量化せずに固有の鍵でマシンを単独で復元します。Apple アカウントは選択肢にありません。どちらにしてもゲストはサインインを拒否するため、サービスプロファイルが trimmed の場合、Launchpad は常に `--accounts-off` を渡します。シートはページに合わせて 600 ポイントまで大きくなり、それを超えるとスクロールするため、ノートパソコンの画面でもボタンが画面内に収まります。
+
+### kernelcache を作り直すファームウェア
+
+**Firmware** では、そのリリース自身の cloudOS でも動作するリリース(`fw catalog` の 3 列目)について、推奨の cloudOS と並べてその cloudOS が選べます。作成処理では、kernelcache ミックスをあなたのユーザ権限で準備し、ヘルパーに root としてリンクさせます。その際に一度だけ認証を求めます。
+
+これらの組み合わせでは、ミックスの準備に `ipsw` ツールを使う古い互換の Core Bundle(2.12.0)のために、Launchpad は引き続き `ipsw` ツールの欄を表示します。Core Bundle 2.12.1 以降はネイティブで展開し、選択したパスは無視します。
+
+iPhone XS Max は iOS 18.1〜18.7.2 を、それぞれのリリース自身の cloudOS 上で、テンプレートなしで、既定では Minimal プリセットで実行します。Standard も動作します(18.6 で確認)。これらの組み合わせでは常に kernelcache を作り直すため、**Firmware** で macOS ビルダーも尋ねられます。
+
+- macOS 15 または 26.0〜26.3 を実行し、リモートログインがオンになっている Mac または macOS 仮想マシンの `user@host`
+- ssh と sudo 用のパスワード。ssh 鍵とパスワードなしの sudo を使う場合は空にします
+
+Launchpad はビルダーを保存しますが、パスワードは保存しません。パスワードは環境変数(`VPHONE_KMUTIL_SSH_PASSWORD`)でのみ `vphone-cli` に渡されます。作成処理は、あなたのユーザ権限で ssh 経由でミックスを準備してリンクします。macOS 26.4 以降ではビルダーが必須です。それより古い Mac でビルダーがない場合は、ヘルパーが root としてミックスをリンクします。
+
+### 作成処理でのテンプレートの使い方
+
+作成処理は、最初に `vm template find` を実行します。
+
+- 最新のテンプレートが一致する場合は、マシンを複製し(`vm create --template <id> --skip-first-boot`)、起動します。
+- 一致しない場合は、同じライブラリ内の一時的なマシン(`template-` と 8 桁の 16 進数の名前)でテンプレートを作ります。通常の手順(復元、ヘルパーを通じた `cfw install`)の後、`vm template trim`、ヘッドレスの `vm template setup --strict`、`vm template adopt --iphone-source … --cloudos-source … --expect <id>` を実行し、その結果からマシンを複製します。
+
+削除すべきアプリが残るとセットアップ起動が失敗し、作成処理のキーが `find` の求めたキーと異なると adopt が失敗するため、以降の作成処理が見つけられない ID で作成結果が保存されることはありません。それぞれが所要時間付きの独立した手順として表示され、失敗した手順には `vphone-cli` が示した理由が表示されます。
+
+New Machine の **Patch Settings** でのパッチごとの上書き設定は、テンプレートキーと同じ方法で分けられます。
+
+- ブートチェーンの上書き設定はキーに含まれます。テンプレートはそれを適用して作られ、`find` もそれを含むテンプレートを探します。
+- ゲストパッチの上書き設定は含まれません。テンプレートはそれを適用せずに作られます。複製の後、作成処理は `fw set-patches` で新しいマシンにそれを記録し、初回起動の前にヘルパーを通じて `cfw update-environment` で書き込みます(**Apply guest patches** の手順)。そのため、ある作成処理でのゲストパッチの選択が、テンプレートを通じて別の作成処理に引き継がれることはありません。
+
+テンプレートを作った後、作成処理はその元になった 2 つの IPSW を削除するかどうかを尋ねます。確認なしに削除されることはありません。
+
+### Launchpad でテンプレートを管理する
+
+- **File > Templates…** には、すべてのライブラリのテンプレートが、そのマシン、軽量化の内容、サイズ、状態とともに表示され、削除もできます。
+- **Guest System…**(マシンのアクションメニューとインスペクタにあります)では、実行中のマシンのサービスプロファイルを切り替えたり、テンプレートが削除したシステムアプリを戻したりできます。
+- インスペクタとマシンの一覧には、各マシンが単独で使っているディスク容量が、そのファイルの割り当て量と並べて表示されます。これは、ほかのどのマシンやテンプレートも保持していないブロックで、そのマシンを削除すると解放されます。それ以前に作成されたローカルの Time Machine スナップショットは、期限が切れるまでそれらのブロックを保持します。
+
+## 関連項目
+
+- [テンプレート](templates.md)
+- [複数マシンの一括作成](many-machines.md)
+- [ファームウェアの準備](../firmware/firmware-preparation.md)
+- [Launchpad CLI](../launchpad/launchpad-cli.md)
diff --git a/Documents/ja/storage/templates.md b/Documents/ja/storage/templates.md
new file mode 100644
index 00000000..7686b1e9
--- /dev/null
+++ b/Documents/ja/storage/templates.md
@@ -0,0 +1,162 @@
+# テンプレート
+
+テンプレートは、`vm create` が新しいマシンを複製する元になる、完成済みで凍結されたマシンです。ある組み合わせのオプションで最初に作成するときにテンプレートが作られ、同じオプションでの以降の作成は数秒で終わり、何もダウンロードしません。このページでは、テンプレートの作成、軽量化、後片付けを制御する方法を説明します。
+
+## テンプレートからマシンを作成する
+
+`vm create` は標準でテンプレートを使います。
+
+```sh
+vphone-cli vm create phone-a --iphone-source … --cloudos-source … # builds the template, clones phone-a
+vphone-cli vm create phone-b --iphone-source … --cloudos-source … # clones phone-b, no restore
+vphone-cli vm create phone-c --template 3f2a91c0d4e7 --cpu 4 --memory 6144
+```
+
+- 一致するテンプレートがある場合、`vm create` はそこから新しいアイデンティティでマシンを複製し、指定された CPU、メモリ、ネットワークを設定して、vphoned を確認するために一度起動します。root 権限も IPSW も必要ありません。
+- ない場合は、必要に応じて IPSW をダウンロードし、作業用フォルダで処理全体を実行してテンプレートを作成して凍結し、そこからマシンを複製します。
+- `--template <id>` は、識別子または一意に決まる 4 桁以上の先頭部分でテンプレートを指定して複製します。IPSW のオプションは受け付けません。`--device`、`--preset`、`--disk-size`、軽量化のスイッチを指定する場合は、テンプレートの値と一致している必要があります。複製でこれらを変えることはできません。
+- `--no-template` は、マシンを単独で復元し、固有の鍵を持たせます。軽量化のスイッチは受け付けません。
+
+仮想マシンを手動でテンプレートにする方法、`vm create` が使うテンプレートを調べる方法、Launchpad がテンプレートを作る方法については、[テンプレートの作成と検索](template-building.md)をご覧ください。
+
+## テンプレートの照合
+
+何かを復元する前に、`vm create` はオプションと 2 つの IPSW からテンプレートキーを求めます。キーに含まれるもの:
+
+- ゲストのデバイス
+- iOS と cloudOS のバージョンとビルド
+- パッチプリセットと、それが解決されるブートチェーンのパッチ。バンドルに同梱されていないプリセット(プリセットファイル、または `~/.vphone/patches_presets` にあるもの)の場合は、ゲストのパッチも含め、解決されるすべてのパッチが含まれます。このようなプリセットは同じ識別子のまま内容が変わることがあり、複製はテンプレートのゲストパッチを引き継ぐためです
+- バンドルのシリーズ(2.9.x なら `2.9`)
+- ディスクサイズ
+- ゲストの System ボリュームから削減するもの(`--trim`)と残す言語
+- 下記の軽量化のスイッチ
+
+CPU、メモリ、画面、ネットワークはキーに含まれません。
+
+ビルドは、IPSW がローカルのファイルであるか、すでに IPSW キャッシュにある場合はその IPSW から求めます。それ以外の場合は、[`vm template find`](template-building.md) と同じ方法で、同じ 2 つのソースで記録されたテンプレートから求めます。削除されたローカルの IPSW は、存在しないものとして扱われます。
+
+### テンプレートの作成
+
+一致するテンプレートがない場合、処理全体が `.templates/.building-<id>-<uuid>/` で実行されます:`cfw install`、オフラインでの削減、そしてセットアップ起動。結果は凍結され、1 回の操作で `<library>/.templates/<id>/` に名前が変更されます。
+
+- 復元ツリーは、`--keep-artifacts` の指定にかかわらず、凍結の前に削除されます。残しておくと約 11 GB がテンプレートの存続期間中ずっと占有され、どの複製もそれを使えないためです。`--keep-artifacts` で復元ツリーが残るのは `--no-template` の場合だけです。`vm template adopt` も復元ツリーを削除します。
+- 同じキーで 2 つ目の `vm create` を実行すると、2 つ目のコピーを復元せずに最初の処理を待ちます。
+- 失敗した作成処理は、調査できるように作業用フォルダに残ります。
+
+テンプレートは作成中にセットアップ起動のために一度だけ起動し、凍結された後は二度と起動しません。
+
+## オフラインでの削減
+
+`cfw install` の後、テンプレートの作成処理は、ゲストが必要としないシステムファイルを System ボリュームから削除します。これはボリュームをホストにマウントしてオフラインで行います。段階は `vm create` の `--trim`(標準は `standard`)と `vm template trim` の `--tier` で選びます。
+
+| 段階 | 削除するもの | 目安 |
+| --- | --- | --- |
+| `none` | なし | |
+| `conservative` | `usr/standalone/update` の中身(ソフトウェアアップデート用の RAM ディスク、ベースバンドのファームウェア) | 0.35 GB |
+| `standard` | conservative に加え、AirPods/Beats のペアリング用アセット(`PreinstalledAssetsV2/RequiredByOs/com_apple_MobileAsset_SharingDeviceAssets`)、文字盤(`NanoTimeKit/FaceBundles`)、残さないすべての言語の `LinguisticData/RequiredAssets_*.bundle` | 1.2 GB |
+| `aggressive` | 予約済み:ゲストで検証されるまでは拒否されます | |
+
+`--keep-languages`(標準は `en,zh-Hans,zh`。英語は常に残ります)で、`standard` が残す言語を選びます。段階、リストのバージョン、残す言語はテンプレートキーに含まれる(`standard/1/en,zh,zh-Hans`)ため、削減の内容が異なるテンプレートが一致することはありません。
+
+> [!WARNING]
+> 削減は元に戻せません。複製でファイルを取り戻すことはできません。
+
+削除したファイルは、最初は何も容量を解放しません。ゲストの元のシステムスナップショット(`cfw install` が残す `orig-fs.disabled.rn-*`)がまだすべてのブロックを保持しており、ホストからは root でも削除できないためです。セットアップ起動の最初の手順でこれが削除され、その時点で初めて容量が戻ります。そのため、セットアップ起動を行わないテンプレートでは削減は拒否され、削減したテンプレートはスナップショットがなくなってから初めて凍結または adopt されます。
+
+`vm template trim` には root 権限は不要です。テンプレートから複製されていない停止中のマシン、または未完成の `.building-…` フォルダで実行でき、凍結されたテンプレートは拒否します。
+
+## セットアップ起動と軽量化
+
+セットアップ起動は、すべての複製が始まるべき状態にテンプレートを仕上げます。テンプレートを一度起動し、vphoned を通じて次の順に処理します。
+
+1. `cfw install` が残した APFS スナップショット `orig-fs.disabled.rn-*` を削除します(約 20 MB を保持しており、さらに削除されるまでは System ボリュームから削減したすべてのファイルも保持しています)。
+2. 設定アシスタントを省きます(`setup.skip`)。
+3. 初回起動時の処理が落ち着くのを待ちます(`setup.settle`、最大 10 分)。初回起動時に installd が削除可能なシステムアプリを展開します。
+4. システムアプリを削除します(`apps.remove_system`、バックアップはゲスト内に保持)。
+5. サービスプロファイルを適用します(`services.profile.apply`)。これにはサインインのフォローアップ用デーモン(`followupd`、`appleidsetupd`)をオフにすることも含まれます。
+6. 再起動して確認します:スナップショットが残っていないこと、セットアップが完了していること、プロファイルのサービスが 1 つも実行されていないこと、削除したアプリがないこと、vphoned が応答すること。
+7. この起動のために `vphone-vm` が固定したデバイス名を消去し、ゲストを正常にシステム終了します。
+
+各手順には期限があります。手順が失敗すると仮想マシンは停止し、何も記録されず、作成処理は凍結されないまま残ります。`vm create` は失敗した手順と再試行の方法を表示します。
+
+| スイッチ | 標準 | 効果 |
+| --- | --- | --- |
+| `--slim on\|off` | on | `off` にすると何も削減せず、すべてのアプリとサービスを残します。セットアップ起動は引き続き実行され、セットアップが省かれ、スナップショットが削除されます。 |
+| `--trim none\|conservative\|standard` | standard | 上記のオフラインでの削減。 |
+| `--keep-languages <list>` | `en,zh-Hans,zh` | `--trim standard` が残す言語。 |
+| `--service-profile trimmed\|none` | trimmed | vphoned の trimmed プロファイル:App Store のデーモンやサインインのフォローアップを含む約 140 個の launchd ジョブをオフにします。このプロファイルの iPhone は Apple Watch とペアリングできません(`Research/Guest/watch_pairing.md` をご覧ください)。 |
+| `--remove-apps on\|off` | on | App Store、ホーム、TV、News、FaceTime、iTunes Store、メッセージ、ゲーム、探す、ウォレットを削除します。カメラと電話は残ります。 |
+| `--keep-apps <ids>` | なし | そのリストのうち残すアプリのバンドル ID をコンマ区切りで指定します(`com.apple.findmy,com.apple.Passbook`)。 |
+| `--accounts-off` | off | `akd`、`amsaccountsd`、`appleaccountd` もオフにします。ゲストは Apple アカウントにサインインできなくなります。 |
+
+それぞれの選択はキーに含まれるため、軽量化の内容が異なるテンプレートは共存でき、それぞれを求める作成処理にだけ使われます。サービスプロファイルの制限については、[Apple Watch のペアリングに関する記録](../../../Research/Guest/watch_pairing.md)をご覧ください。
+
+削除したアプリとプロファイルは、複製で `vphone-launchpad-cli guest rpc` または Launchpad の **Guest System** を使って元に戻せます。
+
+- `apps.restore_system` は、バックアップからアプリを戻します。
+- `services.profile.apply {"profile":"none"}` は、プロファイルがオフにしたものだけを正確にオンに戻します。
+
+### 複製が引き継ぐもの
+
+複製はテンプレートから次のものを引き継ぎます:完了したセットアップ、セットアップ起動が残した状態のアプリとサービス、installd とインデックス作成処理が行った初回起動時の処理、その起動時点の Data ボリューム。
+
+デバイス名は引き継ぎません。テンプレートでの固定は消去されるため、複製は自身の仮想マシンが接続して複製の名前を固定するまで `iPhone` と表示します。また、アイデンティティが新しくなるため、Mac は再び「このコンピュータを信頼しますか?」と尋ねます。
+
+## 共有される秘密情報
+
+> [!WARNING]
+> 1 つのテンプレートから複製したマシンはすべて、テンプレートと、また互いに、SEP のルートシークレット、Data ボリュームの鍵、復元とセットアップ起動で書き込まれたデータを共有します。理論上は、ある複製が別の複製の Data ボリュームを復号できます。
+
+マルチデバイスの研究のために Apple のサービスにサインインする場合など、固有の鍵が必要なマシンは `--no-template` で作成してください。
+
+複製は、`vm clone --new-identity` と同じく、初回起動時に新しい ECID、UDID、MAC アドレスを得ます。APFS 上では、変更されていないすべてのブロックをテンプレートと共有します。新しい複製は書き込みを始めるまでほとんど容量を使わず、軽量化したテンプレートでは初回起動時に書き込む処理も少なくなります。
+
+## テンプレートを管理する
+
+```sh
+vphone-cli vm template list # id, key summary, STALE with the reasons
+vphone-cli vm template show <id> --json
+vphone-cli vm template trim myphone --tier standard # trim a stopped VM before adopting it
+vphone-cli vm template setup myphone # the setup boot, on a stopped VM
+vphone-cli vm template adopt myphone # freeze a stopped, newly created VM into a template
+vphone-cli vm template delete <id>
+```
+
+### 古くなったテンプレート
+
+この `vphone-cli` が別のバンドルシリーズに属する場合、キーの形式が古い場合、プリセットが別のブートチェーンのパッチに解決されるようになった場合、またはパッチの記録が計画と一致しない場合、テンプレートは古くなったもの(STALE)として表示されます。古くなったテンプレートは使われません。そのキーで `vm create` を実行すると失敗し、そのテンプレートの名前が表示されます。削除すれば、次の `vm create` で新しいテンプレートが作られます。
+
+### 仮想マシンを adopt する
+
+`vm template adopt <vm>` は、停止中の仮想マシンを、その記録から求められるキーでテンプレートにします。使われる記録は `restore-info.json`、`PatchPlan.plist`、`config.plist`、ディスクイメージ、Launchpad の `launchpad.json`、そして `vm template trim` と `vm template setup` が `Template.plist` に記録した手順です。その仮想マシンは `vm list` から消えます。
+
+仮想マシンは、セットアップ起動の直後に adopt してください。それ以降にゲストで行われたことは、すべての複製に引き継がれます。スナップショットのある仮想マシンは拒否され、`--force` を指定しない限り、古くなったテンプレートになる仮想マシンも拒否されます。
+
+### 凍結されたテンプレートは起動しない
+
+`vm launch` と `vphone-vm` は、DFU であっても凍結されたテンプレートを拒否します。マシン名で `.templates` の中を指定することはできないため、`vm launch`、`clone`、`export`、`rename`、`delete` が誤ってテンプレートを対象にすることはありません。凍結後にテンプレートが起動すると、以降のすべての複製が引き継ぐブロックに状態が書き込まれ、それ以前に作られた複製はそれらのブロックを共有しなくなります。
+
+### テンプレートを使っているマシン
+
+テンプレートから複製したマシンは、そのテンプレートを `TemplateSource.plist` に記録します。そのマシンを `vm clone` するとこの記録は残り(コピーもテンプレートのブロックを共有するため)、`vm export` では含まれません(読み込んだマシンは何も共有しないため)。記録にはテンプレートのビルドも含まれるため、テンプレートを削除して同じキーで作り直した場合、古いテンプレートから複製したマシンは数に入りません。それらは新しいテンプレートのブロックを共有していないためです。
+
+`vm template list` と `show` は、各テンプレートを使っているマシンとディスク上のサイズを表示し、`vm info` はマシンのテンプレートを表示します。まだ存在するテンプレートから複製された最後のマシンを `vm delete` で削除すると、その旨が表示されます。テンプレート自体が削除されることはありません。
+
+```text
+note: template 3f2a91c0d4e7 (~17.40 GB) is no longer used by any machine; remove it with `vphone-cli vm template delete 3f2a91c0d4e7`
+```
+
+### テンプレートを削除する
+
+`vm template delete <id>` はテンプレートを削除します。そこから複製したマシンは引き続き動作します。それらのマシンがまだテンプレートと共有しているブロックは、マシンがそのブロックを変更するか削除されたときに初めて解放されるため、複製が残っている間は、テンプレートを削除しても解放される容量はそのサイズより少なくなります。
+
+表示されるメモで、どちらの場合かがわかります。テンプレートを使っているマシンがあり、共有ブロックはそれらのマシンが変更するか削除されるまで割り当てられたままになる場合と、使っているマシンがなく、削除するとそのブロックが解放される場合です。テンプレートが存在していた間に作成されたローカルの Time Machine スナップショットは、期限が切れるまでそれらのブロックを保持することがあります。`--json` と `--force` を指定すると、同じ情報が出力されます。
+
+テンプレートは `vm list` には表示されませんが、ディスク容量を使います。`~/.vphone/machines/.templates` を確認してください。また、`du` はテンプレートとその各複製をそれぞれフルサイズで数えることに注意してください。
+
+## 関連項目
+
+- [テンプレートの作成と検索](template-building.md)
+- [複数マシンの一括作成](many-machines.md)
+- [仮想マシン間でのディスク容量の共有](sharing-disk-space.md)
+- [ライブラリ、ファームウェア、バックアップ](library-and-backups.md)
diff --git a/Documents/ko/README.md b/Documents/ko/README.md
new file mode 100644
index 00000000..9cfd4b97
--- /dev/null
+++ b/Documents/ko/README.md
@@ -0,0 +1,70 @@
+# vphone 설명서
+
+vphone이 처음이라면 [개요](get-started/overview.md)를 읽은 뒤 [빠른 시작](get-started/quick-start.md)을 따라 하세요.
+
+## 시작하기
+
+| 페이지 | 내용 |
+| --- | --- |
+| [개요](get-started/overview.md) | vphone이 무엇이고, 무엇이 필요하며, 어떤 프로그램이 포함되는지 |
+| [빠른 시작](get-started/quick-start.md) | Launchpad 또는 코딩 에이전트로 첫 가상 머신 만들기 |
+| [호스트 설정](get-started/host-setup.md) | Mac의 SIP, AMFI, Research Guests 설정 |
+| [다운로드](get-started/downloads.md) | 공증된 Launchpad 버전과 그에 맞는 `VPhone.bundle` 버전 |
+
+## 머신
+
+| 페이지 | 내용 |
+| --- | --- |
+| [가상 머신 생성 및 실행](machines/create-and-run.md) | 터미널에서 가상 머신 만들기, 시작, 중지 |
+| [부트 ROM](machines/boot-roms.md) | OpenAVB/OpenSEP와 Apple ROM 사이의 전환 |
+| [자동화 API](machines/automation-api.md) | 선택적으로 사용하는 로컬 HTTP 및 WebSocket 인터페이스 |
+| [기기 이름과 시계](machines/device-name-and-clock.md) | 게스트가 가상 머신 이름과 Mac의 시계에서 가져오는 것 |
+| [패키지 환경](machines/package-environment.md) | 게스트에 패키지 관리자 설치 및 제거 |
+
+## 펌웨어와 기기
+
+| 페이지 | 내용 |
+| --- | --- |
+| [호환성](firmware/compatibility.md) | 검증된 iPhone 및 cloudOS 펌웨어 조합 |
+| [펌웨어 준비](firmware/firmware-preparation.md) | GPU 드라이버 복원, 최신 cloudOS용 kernelcache 믹스 |
+| [다른 iPhone 모델](firmware/iphone-models.md) | 다른 iPhone 모델의 IPSW로 iOS 실행 |
+| [iPadOS 게스트](firmware/ipados.md) | iOS 대신 iPadOS 실행 |
+
+## 저장소와 백업
+
+| 페이지 | 내용 |
+| --- | --- |
+| [보관함과 백업](storage/library-and-backups.md) | 가상 머신과 캐시의 위치, 복제와 내보내기 |
+| [스냅샷](storage/snapshots.md) | 중지된 가상 머신의 디스크를 저장하고 되돌리기 |
+| [템플릿](storage/templates.md) | 한 번의 복원으로 여러 가상 머신 만들기 |
+| [템플릿 만들기](storage/template-building.md) | 가상 머신을 템플릿으로 만들고 템플릿 찾기 |
+| [디스크 공간 공유](storage/sharing-disk-space.md) | 따로 복원한 가상 머신을 위한 `vm rebase` |
+| [여러 머신 만들기](storage/many-machines.md) | plist로 `vm create-bulk` 실행 |
+| [셰이더 캐시](storage/shader-cache.md) | 기존 가상 머신의 영구 셰이더 캐시 |
+
+## 네트워크
+
+| 페이지 | 내용 |
+| --- | --- |
+| [네트워크 모드](networking/overview.md) | 모드 선택, 실행 중인 가상 머신의 네트워크 분리 |
+| [터널 모드](networking/tunnel.md) | VPN이나 프록시 앱을 사용하는 Mac |
+| [MAC 및 IP 주소](networking/addresses.md) | 저장된 MAC, 이전 임대, 고정 주소 |
+| [포트 포워딩](networking/port-forwarding.md) | Mac의 포트를 게스트로 전달하기 |
+| [네트워크상의 이름](networking/names.md) | 게스트의 `.local` 이름과 게스트에서의 Mac 이름 |
+| [머신 간 연결](networking/peers.md) | 하나의 공유 네트워크에 있는 `nat` 머신 |
+
+## Launchpad와 번들
+
+| 페이지 | 내용 |
+| --- | --- |
+| [Launchpad 명령줄](launchpad/launchpad-cli.md) | `vphone-launchpad-cli`로 Launchpad 제어하기 |
+| [코어 번들과 로컬 빌드](launchpad/core-bundles.md) | 머신을 번들에 연결하기, 로컬 빌드 테스트 |
+| [번들 통합](launchpad/bundle-integration.md) | `VPhone.bundle`에 포함된 것과 앱에서 사용하는 방법 |
+
+## 도움말
+
+| 페이지 | 내용 |
+| --- | --- |
+| [문제 해결](help/troubleshooting.md) | 실행 거부, 복원 실패, 게스트 문제 |
+
+구현 기록, 패치 기록, 전체 API 레퍼런스는 [연구 기록](../../Research/README.md)에 있으며, 영어로만 제공됩니다.
diff --git a/Documents/ko/firmware/compatibility.md b/Documents/ko/firmware/compatibility.md
new file mode 100644
index 00000000..3d29ce92
--- /dev/null
+++ b/Documents/ko/firmware/compatibility.md
@@ -0,0 +1,166 @@
+# 펌웨어 호환성
+
+어떤 게스트 펌웨어와 cloudOS 조합이 어떤 호스트에서 부팅되는 것으로 확인되었는지 정리합니다. 새 머신에 사용할 릴리스를 고르기 전에, 또는 생성에 실패해서 그 조합이 테스트된 적이 있는지 알고 싶을 때 확인하세요.
+
+현재 카탈로그가 이 Mac에서 제공하는 항목을 보려면 다음을 실행합니다.
+
+```sh
+vphone-cli fw catalog
+```
+
+> [!NOTE]
+> v2.0.0부터 vphone은 `config.plist`에 `schemaVersion=2`가 있는 머신만 시작합니다. 이전 릴리스에서 만든 머신은 `vm create`로 다시 만드세요. 기존 머신을 그 자리에서 업그레이드하는 방법은 없습니다. 아래 결과는 테스트된 조합을 나타내며, 이전 머신 번들과의 호환성을 뜻하지 않습니다.
+
+## 테스트된 환경
+
+다음은 네이티브 JB 파이프라인으로 처음부터 끝까지 실행한 iPhone17,3 조합입니다. PR #486의 두 행([PR #486](https://github.com/Lakr233/vphone-cli/pull/486))은 잠금 화면까지 도달하고 vphoned ping에 응답했습니다. 새로 실행한 26.6.2 `vm create`도 모든 단계를 마치고 첫 부팅 ping 후 정상적으로 종료되었습니다.
+
+| 검증 | iPhone 복원 IPSW | PCC/cloudOS IPSW | 관찰된 결과 |
+| --- | --- | --- | --- |
+| PR #486 | `17,3_26.6.2_23G90` | `26.4-23E5207q` | JB 패치, 복원, CFW, 부팅, vphoned ping |
+| PR #486 | `17,3_27.0_24A435` | `26.4-23E5207q` | JB 패치, 복원, CFW, 부팅, vphoned ping |
+| 연구용 보드 | `17,3_26.6_23G71` | `26.6-23G71` | CLI에서 standard 및 Minimal 프리셋, Launchpad에서 standard(2026-10-20): 디바이스 트리와 SEP 변환, kernelcache 믹스, 복원, CFW, 부팅, vphoned ping |
+| 연구용 보드 | `17,3_26.5_23F77` | `26.5-23F75` | CLI에서 standard 프리셋(2026-10-20): 임시 cloudOS 복원으로 얻은 GPU 드라이버, kernelcache 믹스, 복원, CFW, 부팅, vphoned ping |
+| 연구용 보드 | `17,3_26.4_23E246` | `26.4-23E244` | CLI에서 standard 프리셋(2026-10-20): 임시 cloudOS 복원으로 얻은 GPU 드라이버, kernelcache 믹스, 복원, CFW, 부팅, vphoned ping |
+| 연구용 보드 | `Watch7,18_26.4_23T240` | `26.4-23E244` | CLI와 Launchpad에서 `watchos` 프리셋(2026-10-20): watch kernelcache 믹스, 복원, 부팅, vphoned ping |
+| 연구용 보드 | `11,6_18.7.2_22H124` | `18.7.2-22H43` | CLI에서 Minimal 프리셋(2026-10-21): 임시 cloudOS 복원으로 얻은 GPU 드라이버, macOS 15.6.1의 kmutil이 ssh로 링크한 iOS 18 kernelcache 믹스, 복원, 부팅, vphoned ping. 화면, 잠금 화면, 잠금 해제, 홈 스와이프 확인 |
+| 연구용 보드 | `11,6_18.1_22B83` | `18.1-22B83` | CLI에서 Minimal 프리셋(2026-10-21): 임시 cloudOS 복원으로 얻은 GPU 드라이버, macOS 15.6.1의 kmutil이 ssh로 링크한 kernelcache 믹스, 복원, 부팅, vphoned. Hello 화면, 잠금 화면, 잠금 해제, 홈 스와이프 확인 |
+| 연구용 보드 | `11,6_18.5_22F76` | `18.5-22F76` | CLI에서 Minimal 프리셋(2026-10-21): 임시 cloudOS 복원으로 얻은 GPU 드라이버, macOS 15.6.1의 kmutil이 ssh로 링크한 kernelcache 믹스, 복원, 부팅, vphoned. 잠금 화면, 잠금 해제, 홈 스와이프 확인 |
+| 연구용 보드 | `11,6_18.6_22G86` | `18.6-22G86` | Launchpad CLI에서 standard 프리셋(2026-10-24): kernelcache 믹스(캐시 사용), 복원, CFW, 부팅, vphoned, Hello 화면. 두 Frida 패치를 허용한 상태에서 Frida 17.24.3 attach, spawn, Interceptor, Stalker |
+
+### 사용할 cloudOS
+
+특별한 이유가 없다면 cloudOS 26.4 베타(`26.4-23E5207q`)를 사용하세요. 게스트의 커널, SEP, 디바이스 트리가 유래하는 식별 정보인 `vphone600ap`를 포함한 가장 최신 cloudOS이며, `vphone-cli` 외에는 아무것도 필요하지 않습니다.
+
+그 이후의 모든 cloudOS(2026-10-03 확인)에는 PCC 보드와 `vresearch101ap`만 있습니다. `SupportedProductTypes`에서 `iPhone99,11`이 빠졌고, `kernelcache.*.vphone600`, `sep-firmware.vphone600`, `DeviceTree.vphone600ap`도 없습니다. 이런 cloudOS에서는 연구용 보드가 그 역할을 대신합니다(Research Board 패치 세트).
+
+- `fw patch`는 연구용 보드의 디바이스 트리와 SEP를 vphone600용으로 바꾸고, 해당 kernelcache의 레시피에 따라 vphone600 가상화 kext를 넣어 kernelcache를 다시 빌드합니다.
+- KDK 추출은 네이티브로 실행되며, 링크만 root 권한이 필요합니다(`vphone-cli fw kernelcache`). [kernelcache 레시피](../../../VPhoneExecutable/VPhoneVirtualization/Resources/kernelcache_recipes/README.md)와 [펌웨어 준비](firmware-preparation.md)를 참고하세요.
+- `fw prepare`는 레시피가 없는 cloudOS를 거부합니다.
+- `fw catalog`는 각 iOS 릴리스 자체의 cloudOS를 권장 cloudOS 옆에 표시하며, Launchpad는 이를 **Firmware** 아래에서 제공합니다.
+
+| cloudOS | `vresearch101ap` | `vphone600ap` | kernelcache 레시피 |
+| --- | --- | --- | --- |
+| `26.4-23E5207q`(베타) | 예 | 예 | 필요 없음 |
+| `26.4-23E244` | 예 | 아니요 | 예 |
+| `26.4.1-23E254` | 예 | 아니요 | 아니요 |
+| `26.5-23F75` | 예 | 아니요 | 예 |
+| `26.5.2-23F83` | 예 | 아니요 | 아니요 |
+| `26.6-23G71` | 예 | 아니요 | 예 |
+| `26.6.1-23G82` | 예 | 아니요 | 아니요 |
+| `26.7-23H20` | 예 | 아니요 | 예 |
+
+다른 iPhone 및 iPad 버전도 `26.4-23E5207q`에서 동작할 수 있지만, 같은 종단 간 검증은 거치지 않았습니다.
+
+### iOS 18 게스트
+
+iOS 18.1~18.7.2는 해당 릴리스 자체의 cloudOS에서, iPhone XS 계열 IPSW의 사용자 영역으로 실행됩니다.
+
+- `vm create --device iPhone11,6`으로 만듭니다. 기본 프리셋은 Minimal이며, `--preset standard`는 18.6에서 확인했습니다.
+- `fw catalog --device iPhone11,6`으로 릴리스 목록을 볼 수 있습니다.
+- 이 커널은 kernel-first 레이아웃입니다. macOS 26.4부터는 macOS 15 또는 26.0~26.3을 실행하는 다른 Mac이나 macOS 가상 머신이 ssh로 믹스를 링크합니다(`VPHONE_KMUTIL_SSH`, [펌웨어 준비](firmware-preparation.md) 참고).
+- Launchpad는 이를 iPhone XS Max로 제공하며, 그 Mac을 macOS 빌더로 사용합니다.
+
+18.1, 18.5, 18.7.2는 가상 머신에서 확인했으며, 나머지 네 레시피는 아직 부팅해 보지 않았습니다.
+
+### iOS 27.0.1의 iPhone17,3
+
+iOS 27.0.1(24A446)은 번들 2.5.0 이하에서 첫 부팅에 실패합니다(2026-10-04 재현, 수정하지 않은 Apple launchd로도 동일). TXM의 selector-24 사전 검사가 init 시점에 모든 바이너리를 거부하고, 부팅이 `unexpected SIGKILL of init`으로 패닉합니다. `txm-boot-precheck_admission` 패치가 이를 해결합니다([연구 기록](../../../Research/Firmware/txm_selector24_cms_gate.md) 참고). 이 패치를 적용하면 `26.4-23E5207q`의 iPhone17,3 27.0.1이 게스트까지 부팅되고 vphoned `device.info`에 응답합니다(같은 날 확인). 이 패치가 포함된 첫 릴리스는 번들 2.6.0입니다.
+
+## macOS 26.6.2 호스트
+
+2026-10-23에 Core Bundle 2.12.1로, 2026-10-24에 Core Bundle 2.12.2로 다시 Mac mini M4 호스트(Mac16,10, 16 GB, macOS 26.6.2 25G83)에서 확인했습니다. 모든 머신은 CLI에서 처음부터 만들었습니다. 연구용 보드 조합은 사용자 권한으로 kernelcache 믹스를 준비하고 sudo로 링크한 뒤 `sudo vphone-cli vm create`를 실행했습니다. '기본값'은 이 Mac에서 `fw catalog`가 해당 기기에 제공하는 가장 최신 조합으로, Launchpad의 New Machine이 선택하는 조합입니다. 각 머신은 이후 헤드리스로 두 번 부팅했으며, vphoned가 응답하고 `device.info`가 해당 릴리스를 보고했으며 게스트의 시리얼 로그에 패닉이 없었습니다.
+
+| 게스트 | 펌웨어 | cloudOS | 결과 |
+| --- | --- | --- | --- |
+| iPhone17,3 | iOS 27.0.1(기본값) | `26.4-23E5207q` | 템플릿 빌드, 복제, 2회 부팅 |
+| iPhone18,2 | iOS 27.0.1(기본값) | `26.4-23E5207q` | 템플릿 빌드, 복제, 2회 부팅 |
+| iPad16,1 | iPadOS 27.0.1(기본값) | `26.4-23E5207q` | 템플릿 빌드, 복제, 2회 부팅 |
+| iPhone17,3 | iOS 26.6.2 | `26.4-23E5207q` | 템플릿 빌드, 복제, 2회 부팅 |
+| iPhone17,3 | iOS 26.6.2 | `26.6-23G71` | 연구용 보드: 네이티브 KDK 추출, 인증 스텁이 남지 않은 macOS 26 링크, kernelcache 패치 28개, 2회 부팅 |
+| iPhone17,3 | iOS 26.5 | `26.5-23F75` | 연구용 보드, 위와 동일 |
+| iPhone17,3 | iOS 26.4 | `26.4-23E244` | 연구용 보드, 위와 동일 |
+| iPhone17,3 | iOS 18.6.2 | `26.1-23B85` | 템플릿 빌드, 복제, 2회 부팅 |
+| iPhone11,6 | iOS 18.7.2(기본값) | `18.7.2-22H43` | Minimal, macOS 15.7.7 가상 머신의 kmutil이 ssh로 믹스 링크, 2회 부팅 |
+| iPhone11,6 | iOS 18.6 | `18.6-22G86` | 위와 동일: 이 레시피의 첫 부팅 |
+| iPhone11,6 | iOS 18.7 | `18.7-22H20` | 위와 동일: 이 레시피의 첫 부팅 |
+| Watch7,18 | watchOS 26.4(기본값) | `26.4-23E244` | `watchos` 프리셋, watch kernelcache 믹스, 2회 부팅 |
+| AppleTV5,3 | tvOS 26.6(기본값) | `26.4-23E5207q` | `tvos` 프리셋, 2회 부팅 |
+| AppleTV14,1 | tvOS 26.6(macOS 26에서 기본값) | `26.4-23E5207q` | `tvos-4k` 프리셋, 26.6 OTA 사용자 영역, 2회 부팅 |
+| AudioAccessory5,1 | HomePod 소프트웨어 27.0(macOS 26에서 기본값) | `26.4-23E5207q` | `homepod-mini` 프리셋, 2회 부팅 |
+| AppleTV14,1 | tvOS 27.0 | — | 다운로드 전에 거부됨: macOS 27 필요 |
+| AudioAccessory5,1 | HomePod 소프트웨어 27.2 | — | 다운로드 전에 거부됨: macOS 27 필요 |
+
+tvOS 27.0(24J361)과 HomePod 소프트웨어 27.2(24K120) OTA는 페이로드를 LZRAVEN으로 압축하며, 이를 풀 수 있는 것은 macOS 27뿐입니다. 이전 Mac에서는 `fw catalog`가 이들을 제외하므로, 해당 기기에 대한 Launchpad의 기본값은 tvOS 26.6과 HomePod 소프트웨어 27.0이 되고, 이 중 하나를 직접 지정하면 다운로드 전에 거부됩니다.
+
+Apple TV 4K(4세대), `AppleTV18,1` / `J265AP`는 초기 구동(bring-up) 용도로만 제공되며, tvOS 27.2 베타(`24K120`)를 사용합니다. Apple TV HD 26.6 복원 기반 위에 그 전체 OTA를 얹고 cloudOS 26.4 베타(`23E5207q`)를 사용합니다. macOS 27과 `tvos-4k` 프리셋이 필요합니다. 2026-10-24에 머신 하나를 복원하고 커스텀 펌웨어를 설치한 뒤 두 번 콜드 부팅하여 vphoned와 기존 TVSetup의 4K 언어 화면까지 도달했지만, 설정 자체는 완료하지 않았습니다. 위의 테스트 표에는 포함되지 않습니다. [초기 구동 기록](../../../Research/Firmware/tvos_support.md#apple-tv-4k-4th-generation)을 참고하세요.
+
+cloudOS 26.7(23H20)에는 짝을 이룰 iPhone 릴리스가 없습니다. iOS 26.6.2의 사용자 영역으로 준비하면 믹스가 링크되고 kernelcache 패치 28개가 적용되지만, CFW 패치 `_vm_fault_enter_prepare`가 그 커널에서 적용 위치를 찾지 못합니다. 아직 부팅되지 않았습니다.
+
+> [!TIP]
+> `vphone-escalator`는 허용 목록을 amfid의 메모리에 보관하므로, amfid가 재시작되면 허용 목록이 사라집니다. 이 호스트에서도 실행 도중 한 번 그런 일이 있었습니다. Launchpad는 AMFI가 번들을 거부하면 다시 허용합니다. CLI에서는 `host preflight`가 출력하는 `vphone-escalator allow` 명령을 다시 실행하세요.
+
+## 다른 iPhone 모델
+
+iPhone17,3 이외의 모델은 [다른 iPhone 모델](iphone-models.md)에서 설명합니다.
+
+| 호스트 | iPhone 복원 IPSW | PCC/cloudOS IPSW | 관찰된 결과 |
+| --- | --- | --- | --- |
+| Mac17,9 (M5 Pro) 27.0.1 | `18,1_26.6.2_23G90` (iPhone 17 Pro) | `26.4-23E5207q` | Launchpad `vm create`(2.5.1 로컬 번들): 준비, 패치, 복원, CFW, 402x874 pt @3x 홈 화면까지 부팅, `model` iPhone18,1, vphoned ping |
+| Mac17,9 (M5 Pro) 27.0.1 | `18,2_27.0.1_24A446` (iPhone 17 Pro Max) | `26.4-23E5207q` | `kernel-boot-shared_region_size` 패치로 **부팅됨**(2026-10-06, 번들 2.6.0-local.0d5e6f90): `dyld cache mapped system-wide`, 패닉 0회, vphoned가 27.0.1로 응답, 440x956 pt @3x 홈 화면 |
+| Mac17,7 (M5 Max) 26.4 | `19,2_27.0.1_24A446` (iPhone 18 Pro) | `26.4-23E5207q` | 통합된 ARM64E_X1 호환성으로 **부팅됨**(2026-10-17): 깨끗한 오프라인 복원, 루트 봉인 검증, vphoned ping, 설정, Safari, 계산기 실행 |
+
+### iOS 27의 iPhone18,1 및 iPhone18,2
+
+이 기기에는 `kernel-boot-shared_region_size` 패치가 필요합니다([이슈 #596](https://github.com/Lakr233/vphone-cli/issues/596), 27.0 및 27.0.1). 2026-10-06부터 iOS 27 기반의 `standard` 프리셋에서 켜져 있습니다.
+
+27.0.1에서 이 기기의 dyld 공유 캐시는 `sharedRegionSize`를 `0x185804000`으로 기록하는데, 이는 cloudOS 26.4 게스트 커널의 공유 영역 `0x180000000`보다 큽니다. 그래서 `dyld-boot-maxslide`로 슬라이드를 없애도 캐시를 매핑할 수 없습니다. 패치가 없으면 launchd가 첫 부팅에서 `Library not loaded: /usr/lib/libSystem.B.dylib`로 패닉합니다. iPhone17,3의 27.0.1 캐시(`0x17D508000`)는 여전히 들어갑니다.
+
+이 패치는 arm64 영역을 `0x1C0000000`으로 넓힙니다. 26.4 커널 자체의 태스크 맵 상한 아래에 머무는 가장 큰 크기입니다. 머신의 커널에 패치가 들어 있으면(`PatchReceipt.plist`에 기록됨) `cfw install`이 넓어진 영역을 기준으로 캐시를 측정하므로, 이 기기들도 설치되고 부팅됩니다. 위와 같이 iPhone18,2 27.0.1에서 검증했습니다.
+
+패치가 없으면(이전 번들이거나 패치 선택을 해제한 경우) `cfw install`은 패닉하는 게스트를 남기지 않고 이 설명과 함께 해당 캐시를 거부합니다. iOS 27에는 iPhone17,3을 사용하거나, 이 기기에서는 iOS 26을 사용하세요.
+
+## iPadOS
+
+iPad 게스트는 [iPadOS 게스트](ipados.md)에서 설명합니다.
+
+| 호스트 | iPad 복원 IPSW | PCC/cloudOS IPSW | 관찰된 결과 |
+| --- | --- | --- | --- |
+| Mac17,9 (M5 Pro) 27.0.1 | `iPad16,1,iPad16,2_26.6.2_23G90` | `26.4-23E5207q` | 준비, 패치, 복원, CFW(2.2.5 도우미), 744x1133 pt @2x iPadOS 홈 화면까지 부팅, `model` iPad16,1, vphoned ping |
+| Mac17,9 (M5 Pro) 27.0.1 | `iPad16,1,iPad16,2_27.0.1_24A446` | `26.4-23E5207q` | 카탈로그에서 Launchpad `vm create --device iPad16,1`(2.4.0 번들): 준비, 패치, 복원, CFW, 744x1133 pt @2x iPadOS 홈 화면까지 부팅, `model` iPad16,1, `ios_version` 27.0.1, vphoned ping |
+
+## 이전에 보고된 조합
+
+이전 README에 기록된 호스트와 펌웨어 조합입니다. 현재의 단일 모드 흐름보다 앞서거나 같은 vphoned 검증 근거가 없으므로, 현재 지원 범위가 아닌 연구 이력으로 취급하세요.
+
+| 호스트 | iPhone | CloudOS |
+| --------------- | --------------------- | --------------- |
+| Mac16,11 27.0b2 | `17,3_18.6.2_22G100` | `26.1-23B85` |
+| Mac16,8 26.5.1 | `17,3_26.0_23A341` | `26.1-23B85` |
+| Mac16,8 26.5.1 | `17,3_26.0.1_23A355` | `26.1-23B85` |
+| Mac16,12 26.3 | `17,3_26.1_23B85` | `26.1-23B85` |
+| Mac16,12 26.3 | `17,3_26.3_23D127` | `26.1-23B85` |
+| Mac16,12 26.3 | `17,3_26.3_23D127` | `26.3-23D128` |
+| Mac16,12 26.3 | `17,3_26.3.1_23D8133` | `26.3-23D128` |
+| Mac16,11 26.2 | `17,3_26.4_23E246` | `26.4-23E5207q` |
+| Mac16,11 26.2 | `17,3_26.5_23F77` | `26.4-23E5207q` |
+| Mac16,11 27.0b2 | `17,3_26.5.2_23F84` | `26.4-23E5207q` |
+| Mac16,6 26.4.1 | `17,3_26.6_23G71` | `26.4-23E5207q` |
+| Mac16,11 27.0b2 | `17,3_26.6.1_23G83` | `26.4-23E5207q` |
+| Mac16,6 26.6.1 | `17,3_26.6.2_23G90` | `26.4-23E5207q` |
+| Mac16,11 27.0b2 | `17,3_27.0_24A5380h` | `26.4-23E5207q` |
+| Mac16,6 26.4.1 | `17,3_27.0_24A5390f` | `26.4-23E5207q` |
+| Mac16,6 26.6.1 | `17,3_27.0_24A5408d` | `26.4-23E5207q` |
+| Mac16,11 27.0b2 | `17,3_27.0_24A5418b` | `26.4-23E5207q` |
+| Mac16,11 27.0b2 | `17,3_27.0_24A5424a` | `26.4-23E5207q` |
+| Mac16,11 27.0b2 | `17,3_27.0_24A5430a` | `26.4-23E5207q` |
+| Mac16,6 26.6.1 | `17,3_27.0_24A435` | `26.4-23E5207q` |
+
+모든 패치와 각 패치가 적용되는 위치는 [패치 목록](../../../Research/0_binary_patch_comparison.md)을 참고하세요.
+
+## 함께 보기
+
+- [펌웨어 준비](firmware-preparation.md)
+- [다른 iPhone 모델](iphone-models.md)
+- [iPadOS 게스트](ipados.md)
+- [머신 생성 및 실행](../machines/create-and-run.md)
diff --git a/Documents/ko/firmware/firmware-preparation.md b/Documents/ko/firmware/firmware-preparation.md
new file mode 100644
index 00000000..4fbf95f3
--- /dev/null
+++ b/Documents/ko/firmware/firmware-preparation.md
@@ -0,0 +1,71 @@
+# 펌웨어 준비
+
+펌웨어를 패치하기 전에 `vm create`와 `fw prepare`가 두 IPSW로 하는 일과, vphone600 구성 요소가 없는 cloudOS에 필요한 추가 단계를 설명합니다. 단계를 직접 실행하거나, GPU 드라이버를 재사용하거나, 연구용 보드 조합으로 머신을 만들 때 읽으세요.
+
+## GPU 드라이버
+
+`fw prepare`는 하이브리드 iPhone 복원을 빌드하기 전에 cloudOS에서 반가상화 GPU 드라이버를 가져와야 합니다. 그 과정은 다음과 같습니다.
+
+1. 네트워크 장치가 없는 임시 vphone 가상 머신을 만들고 DFU로 시작합니다.
+2. 선택한 cloudOS IPSW를 vphone 자체의 복원 백엔드로 그 가상 머신에 복원합니다.
+3. 복원된 System 볼륨을 읽기 전용으로 마운트하고 GPU 번들을 추출합니다.
+4. 임시 가상 머신을 삭제합니다.
+
+추출한 번들은 cloudOS 빌드별로 `~/.vphone/gpu-drivers/`에 캐시되므로, 같은 cloudOS를 사용하는 이후 머신은 임시 복원을 건너뜁니다.
+
+이전에 추출한 번들을 재사용하려면 `vm create`나 `fw prepare`에 넘기세요.
+
+```sh
+vphone-cli fw prepare myphone \
+ --gpu-driver-bundle /path/to/AppleParavirtGPUMetalIOGPUFamily.bundle
+```
+
+CLI는 번들의 iPhoneOS 플랫폼 버전을 선택한 cloudOS 버전과 대조합니다. 각 복원은 자신의 티켓을 온라인으로 받습니다.
+
+번들에는 arm64e GPU 컴파일러 플러그인도 포함되어 있습니다. `fw prepare`는 패치와 설치 전에 이를 준비된 GPU 번들에 복사합니다.
+
+## 연구용 보드 조합
+
+26.4 베타 이후의 cloudOS에는 vphone600 구성 요소가 없으므로 연구용 보드가 그 역할을 대신합니다([호환성](compatibility.md)의 '사용할 cloudOS' 참고). 연구용 보드의 kernelcache는 vphone600 가상화 kext를 넣어 다시 빌드됩니다. KDK 추출은 사용자 권한으로 네이티브로 실행되며, kmutil 링크만 root 권한이 필요합니다.
+
+1. 평소처럼 `fw prepare`를 실행합니다.
+2. 사용자 권한으로 믹스를 준비합니다.
+
+ ```sh
+ vphone-cli fw kernelcache myphone
+ ```
+
+3. root로 링크합니다.
+
+ ```sh
+ sudo vphone-cli fw kernelcache myphone
+ ```
+
+4. `fw patch`로 계속합니다. `fw patch`는 캐시에서 믹스를 가져옵니다.
+
+`fw kernelcache`의 이전 `--ipsw` 인자는 여전히 받지만 무시됩니다.
+
+## 다른 Mac에서 링크하기
+
+커널은 Apple이 링크한 레이아웃으로만 부팅되며, kmutil은 자신이 실행되는 Mac에서 레이아웃을 가져옵니다.
+
+| 호스트 macOS | 링크할 수 있는 것 |
+| --- | --- |
+| macOS 26.4 이상 | iOS 26.4 이상의 kernelcache(kernel-last) |
+| macOS 15, 그리고 26.0~26.3 | iOS 18 등 이전 kernelcache(kernel-first) |
+
+이 Mac의 레이아웃이 다르면, 다른 Mac이나 macOS 가상 머신이 ssh로 믹스를 링크합니다. `fw kernelcache` 또는 생성 작업에 다음을 설정하세요.
+
+```sh
+export VPHONE_KMUTIL_SSH='user@host'
+export VPHONE_KMUTIL_SSH_PASSWORD='password' # only without ssh keys and passwordless sudo there
+```
+
+준비된 볼륨은 그 Mac의 `/private/var/tmp`에 업로드되어 그곳에서 root로 링크된 뒤 삭제됩니다. 이 Mac에서는 이를 위해 root 권한이 필요하지 않습니다. 다른 Mac에서는 원격 로그인이 켜져 있어야 하며, 해당 사용자가 sudo를 사용할 수 있어야 합니다.
+
+## 함께 보기
+
+- [펌웨어 호환성](compatibility.md)
+- [머신 생성 및 실행](../machines/create-and-run.md)
+- [보관함, 펌웨어, 백업](../storage/library-and-backups.md)
+- [kernelcache 레시피](../../../VPhoneExecutable/VPhoneVirtualization/Resources/kernelcache_recipes/README.md)
diff --git a/Documents/ko/firmware/ipados.md b/Documents/ko/firmware/ipados.md
new file mode 100644
index 00000000..fbc5f006
--- /dev/null
+++ b/Documents/ko/firmware/ipados.md
@@ -0,0 +1,96 @@
+# iPadOS 게스트
+
+vphone 머신에서 iOS 대신 iPadOS를 실행하는 방법입니다. iPad의 사용자 영역, 화면 크기, 멀티태스킹 기능이 필요할 때 사용하세요.
+
+가상 하드웨어는 바뀌지 않습니다. 부트 체인, 커널, SEP, 디바이스 트리는 여전히 PCC cloudOS IPSW(`vresearch101ap` / `vphone600ap`)에서 가져옵니다. 사용자 영역만 iPhone17,3 대신 iPad의 복원 IPSW에서 가져오며, 사용자 영역이 iPad로 인식하도록 디바이스 트리를 다시 씁니다.
+
+![vphone 가상 머신의 iPadOS 홈 화면](../../ipados-demo.jpeg)
+
+## 만들기
+
+### Launchpad에서
+
+1. **New Machine**을 선택합니다.
+2. **Device**에서 iPad를, **iPadOS**에서 릴리스를 선택합니다. 권장 cloudOS가 함께 선택됩니다.
+3. 카탈로그에 없는 IPSW라면 **Source**를 **Custom IPSWs**로 설정하고, **iPhone IPSW** 필드에 iPad IPSW를, 다른 필드에 cloudOS IPSW를 넣습니다.
+
+**Device** 메뉴는 카탈로그에 iPad가 있는 Core Bundle에서만 나타납니다. 터미널에서는 `vphone-launchpad-cli vm create <name> --device iPad16,1`로 같은 작업을 할 수 있습니다.
+
+### vphone-cli로
+
+iPhone IPSW 자리에 iPad 복원 IPSW를 넘깁니다. cloudOS는 같은 릴리스의 iPhone 게스트가 사용하는 것과 같습니다.
+
+```sh
+vphone-cli vm create ipad-mini \
+ --iphone-source 'https://updates.cdn-apple.com/2026SummerFCS/cf7db64d-5866-4bf2-bfff-50a32f58bec3/iPad16,1,iPad16,2_26.6.2_23G90_Restore.ipsw' \
+ --cloudos-source 'https://updates.cdn-apple.com/private-cloud-compute/c0ecdb4b310cf5239ab2b248dd3098eec297dc5aa3bbe6ada27273262b0b8b64'
+
+# The 13-inch iPad Pro (M5), from the IPSW that also carries the 11-inch
+vphone-cli vm create ipad-pro-13 --device iPad17,3 \
+ --iphone-source 'https://updates.cdn-apple.com/2026SummerFCS/<…>/iPad17,1,iPad17,2,iPad17,3,iPad17,4_26.6.2_23G90_Restore.ipsw' \
+ --cloudos-source 'https://updates.cdn-apple.com/private-cloud-compute/c0ecdb4b310cf5239ab2b248dd3098eec297dc5aa3bbe6ada27273262b0b8b64'
+```
+
+릴리스를 찾으려면 다음 명령을 사용합니다.
+
+| 명령 | 표시 내용 |
+| --- | --- |
+| `vphone-cli fw catalog` | 지원되는 모든 iPad의 iPadOS 릴리스와 각 릴리스의 cloudOS |
+| `vphone-cli fw catalog --device iPad16,1` | iPad 한 기종의 릴리스 |
+| `vphone-cli fw prepare --device iPad16,1 --list` | 해당 iPad의 내려받을 수 있는 IPSW |
+| `vphone-cli fw prepare --device iPad16,1 --iphone-version 26.6.2` | IPSW 하나를 찾습니다 |
+
+`--device`를 지정하고 소스를 지정하지 않으면 `vm create`가 해당 iPad의 릴리스 중에서 선택하도록 보여 줍니다.
+
+### 공유 IPSW에서 모델 선택하기
+
+대부분의 iPad IPSW는 여러 모델을 포함하며, iPad Air와 iPad Pro IPSW에는 두 가지 크기가 모두 들어 있습니다. `--device`가 없으면 `fw prepare`는 IPSW에 나열된 첫 번째 모델(11형)을 사용합니다. 13형을 사용하려면 `fw prepare`나 `vm create`에 `--device iPad17,3`을 넘기세요. Launchpad의 New Machine은 **Device**에서 선택한 모델을 넘기며, **Custom IPSWs**에서는 첫 번째 모델을 사용합니다.
+
+<img src="../../ipados/ipad-pro-13-home.jpg" alt="vphone 가상 머신의 iPad Pro 13형 홈 화면" width="360" />
+
+### 수동 단계
+
+수동 단계는 iPhone 게스트와 같습니다. `vm new`, `fw prepare`, `fw patch`, DFU와 `restore`, `cfw install`, `vm launch` 순서입니다. iPad에서 다르게 동작하는 것은 `fw prepare`와 `fw patch`뿐이며, DFU, `restore`, `cfw install`은 그대로 실행됩니다.
+
+## 지원 기기
+
+| 제품 | 모델 | 보드 | 패널 | 포인트 @2x |
+| --- | --- | --- | --- | --- |
+| `iPad16,1` | iPad mini(A17 Pro) | J410AP | 1488x2266 @ 326 ppi | 744x1133 |
+| `iPad15,7` | iPad(A16) | J481AP | 1640x2360 @ 264 ppi | 820x1180 |
+| `iPad15,3` | iPad Air 11형(M3) | J607AP | 1640x2360 @ 264 ppi | 820x1180 |
+| `iPad15,5` | iPad Air 13형(M3) | J637AP | 2048x2732 @ 264 ppi | 1024x1366 |
+| `iPad16,3` | iPad Pro 11형(M4) | J717AP | 1668x2420 @ 264 ppi | 834x1210 |
+| `iPad16,5` | iPad Pro 13형(M4) | J720AP | 2064x2752 @ 264 ppi | 1032x1376 |
+| `iPad17,1` | iPad Pro 11형(M5) | J817AP | 1668x2420 @ 264 ppi | 834x1210 |
+| `iPad17,3` | iPad Pro 13형(M5) | J820AP | 2064x2752 @ 264 ppi | 1032x1376 |
+
+셀룰러 모델(`iPad16,2`, `iPad15,4`, `iPad15,6`, `iPad16,4`, `iPad16,6`, `iPad17,2`, `iPad17,4`)은 대응하는 Wi-Fi 모델과 IPSW를 공유하며 그 모델로 실행됩니다. 가상 머신에는 베이스밴드가 없습니다. `iPad15,8`은 Wi-Fi 보드가 없는 별도의 IPSW로 배포되며 지원되지 않습니다.
+
+테스트된 조합은 [호환성](compatibility.md)의 'iPadOS' 절에 있습니다.
+
+## iPad에서 달라지는 점
+
+- **`fw prepare`**는 `SupportedProductTypes`로 IPSW를 인식하고, 게스트 보드에 맞는 지우기 식별 정보와 `DeviceMap` 항목을 가져오며(iPad IPSW에는 여러 보드가 포함됨), 제품 유형과 iPad의 디스플레이를 머신의 `config.plist`(`guestProductType`, `screenConfig`)에 기록합니다. 복원 트리의 이름은 `iPhoneOS_iPad16,1_<version>_<build>_Restore`입니다. `iPhone` 접두사는 기기를 뜻하는 것이 아니라, 모든 읽기 코드가 일치시키는 복원 트리 명명 규칙입니다.
+- **두 개의 디바이스 트리.** 하이브리드 매니페스트는 보통 `DeviceTree`와 `RestoreDeviceTree`가 같은 vphone600 파일을 가리킵니다. iPad에서는 `DeviceTree`가 사본인 `Firmware/all_flash/DeviceTree.vphone600ap.guest.im4p`를 가리킵니다. 복원은 `restored_external`이 매니페스트와 대조하는 원래 식별 정보(`iPhone99,11`)로 부팅하고, 게스트는 사본으로 부팅합니다.
+- **`fw patch`**는 그 사본에 iPad의 식별 정보와 표시 정보를 넣습니다(패치 세트 `devicetree`, 항목 `devicetree-cfw-ipad_*`).
+ - 루트의 `model`, `target-type`, `target-sub-type`은 보드와 같게 하고(iPad mini는 `iPad16,1`, `J410`, `J410AP`), `compatible`은 보드를 첫 번째로, `VPHONE600AP`를 두 번째로 둡니다.
+ - `/product`: 보드의 아트워크 idiom, 하위 유형과 배율, 제품 이름, 크롬, 카메라와 버튼 형상, 멀티태스킹 기능(`medusa-overlay-app-capability`, `ui-floating-live-app`, `ui-overlay-app`, `ui-pinned-app`, 그리고 스테이지 매니저가 없는 보드에서는 `disable-chamois`), 제품 유형과 고유 모델. 모두 복원 트리에 보존된 보드의 `DeviceTree.<board>.im4p`에서 읽습니다.
+ - iPhone 전용 `syscfg` 자리 표시자(Dynamic Island, 간편 접근, 벨소리 스위치, 음량 버튼 형상, CarPlay, Watch 페어링)는 제거됩니다.
+
+ 가상 하드웨어는 vphone600 설명을 유지합니다. GPU 기능 세트, 프레임버퍼, 메모리 등급, 부트 플래그가 그대로입니다.
+- **LLB**는 iPad 게스트에서 `llb-cfw-display_scale` 패치를 하나 더 받습니다. LLB는 반가상화 디스플레이의 부트 비디오 워드로 `/chosen/display-scale`을 채우는데, 이 값은 항상 3x이고 MobileGestalt가 이 속성을 화면 배율로 사용하므로, iPad는 496x755 포인트 캔버스를 받게 됩니다. 이 패치는 LLB가 iPad 자체의 배율(2x, iPad mini는 744x1133 포인트)을 쓰도록 합니다.
+- **`cfw install`**은 설치된 디바이스 트리를 건드리지 않습니다. iPhone17,3의 복원 후 식별 정보 재작성(`preboot-exp-devicetree_identity`)은 iPad 게스트에서 건너뜁니다.
+- **머신 창**은 `screenConfig`를 따르므로 iPad의 화면비로 열립니다.
+
+<img src="../../ipados/display-scale-3x-before.jpg" alt="LLB 패치 전, 3x 디스플레이 배율의 iPad 게스트" width="240" />
+
+## 다른 iPad 추가하기
+
+iPad 모델을 추가하려면 [`VPhoneGuestDevice`](../../../VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneGuestDevice.swift)에 제품 유형, 보드, 패널을 담은 한 줄만 추가하면 됩니다. 디바이스 트리에 필요한 나머지는 모두 IPSW에 있는 보드 자체의 `DeviceTree.<board>.im4p`에서 읽습니다.
+
+## 함께 보기
+
+- [다른 iPhone 모델](iphone-models.md)
+- [펌웨어 호환성](compatibility.md)
+- [머신 생성 및 실행](../machines/create-and-run.md)
diff --git a/Documents/ko/firmware/iphone-models.md b/Documents/ko/firmware/iphone-models.md
new file mode 100644
index 00000000..0fb76ab3
--- /dev/null
+++ b/Documents/ko/firmware/iphone-models.md
@@ -0,0 +1,67 @@
+# 다른 iPhone 모델
+
+iPhone17,3(iPhone 16) 대신 다른 iPhone의 복원 IPSW에서 iOS를 가져오는 게스트를 실행하는 방법입니다. 특정 모델의 사용자 영역, 패널 크기, 식별 정보가 필요할 때 사용하세요.
+
+[iPad 게스트](ipados.md)와 마찬가지로 가상 하드웨어는 그대로입니다. 부트 체인, 커널, SEP, 디바이스 트리는 여전히 PCC cloudOS IPSW(`vresearch101ap` / `vphone600ap`)에서 가져옵니다. 사용자 영역만 선택한 모델의 IPSW에서 가져오며, 게스트가 부팅하는 디바이스 트리를 그 모델로 보이도록 다시 씁니다.
+
+## 만들기
+
+Launchpad에서 **New Machine**을 선택하고 **Device**에서 모델을, **iOS**에서 릴리스를 선택합니다.
+
+터미널에서 Launchpad를 통해 만들려면 다음을 실행합니다.
+
+```sh
+vphone-launchpad-cli vm create iphone17pro --device iPhone18,1
+```
+
+`vphone-cli`를 사용할 때는 모델의 IPSW와 cloudOS를 넘깁니다.
+
+```sh
+vphone-cli vm create iphone17pro \
+ --iphone-source 'https://updates.cdn-apple.com/2026SummerFCS/f768ecdf-e037-44e6-bfa6-949b6d127c4f/iPhone18,1_26.6.2_23G90_Restore.ipsw' \
+ --cloudos-source 'https://updates.cdn-apple.com/private-cloud-compute/c0ecdb4b310cf5239ab2b248dd3098eec297dc5aa3bbe6ada27273262b0b8b64'
+```
+
+iPhone 모델마다 자체 IPSW가 있으므로, 소스를 명시하면 `--device`가 필요하지 않습니다.
+
+릴리스를 찾으려면 `fw catalog`를 실행합니다. iPhone 16 및 17 모델의 26.0~27.0.1 릴리스(iPhone 17e는 26.3.1부터)와 iPhone 18 Pro의 27.0.1을, 같은 릴리스의 iPhone17,3이 사용하는 cloudOS와 함께 표시합니다. 모델 하나의 릴리스만 보려면 다음을 실행합니다.
+
+```sh
+vphone-cli fw catalog --device iPhone18,1
+```
+
+## 지원 기기
+
+| 제품 | 모델 | 보드 | 패널 | 포인트 @3x |
+| --- | --- | --- | --- | --- |
+| `iPhone17,3` | iPhone 16 | D47AP | 1290x2796 @ 460 ppi | 430x932 |
+| `iPhone17,4` | iPhone 16 Plus | D48AP | 1290x2796 @ 460 ppi | 430x932 |
+| `iPhone17,1` | iPhone 16 Pro | D93AP | 1206x2622 @ 460 ppi | 402x874 |
+| `iPhone17,2` | iPhone 16 Pro Max | D94AP | 1320x2868 @ 460 ppi | 440x956 |
+| `iPhone17,5` | iPhone 16e | V59AP | 1170x2532 @ 460 ppi | 390x844 |
+| `iPhone18,3` | iPhone 17 | V57AP | 1206x2622 @ 460 ppi | 402x874 |
+| `iPhone18,4` | iPhone Air | D23AP | 1260x2736 @ 460 ppi | 420x912 |
+| `iPhone18,1` | iPhone 17 Pro | V53AP | 1206x2622 @ 460 ppi | 402x874 |
+| `iPhone18,2` | iPhone 17 Pro Max | V54AP | 1320x2868 @ 460 ppi | 440x956 |
+| `iPhone18,5` | iPhone 17e | V159AP | 1170x2532 @ 460 ppi | 390x844 |
+| `iPhone19,2` | iPhone 18 Pro | V63AP | 1206x2622 @ 460 ppi | 402x874 |
+
+iPhone17,3을 포함한 모든 모델은 자체 디바이스 트리에서 패널과 식별 정보를 가져옵니다. iPhone17,3의 패널은 원래부터 사용하던 디스플레이 그대로입니다.
+
+iPhone 17 Pro, 17 Pro Max, 18 Pro는 부팅 검증 기록이 있습니다. [호환성](compatibility.md)의 '다른 iPhone 모델' 절을 참고하세요. iPhone 17 Pro와 17 Pro Max는 iOS 27에서 패치가 필요하며, 그 내용도 같은 곳에 있습니다.
+
+> [!WARNING]
+> iPhone19,2는 ARM64E_X1을 사용합니다. X1을 네이티브로 지원하지 않는 호스트에서는 standard 프리셋이 지원되지 않는 명령어를 낮춰 변환하며, 이 때문에 PC에 묶인 포인터 인증이 약해집니다.
+
+## 다른 iPhone에서 달라지는 점
+
+[iPadOS 게스트](ipados.md)의 'iPad에서 달라지는 점'에 나열된 내용이 모두 적용되며, 두 가지가 다릅니다.
+
+- 보드의 `/product` 값이 같은 방식으로 vphone600 자리 표시자를 대체하지만, iPhone 보드는 iPhone 속성을 유지합니다. Dynamic Island, 간편 접근, OLED, 음량 버튼 형상, CarPlay, Watch 페어링은 제거되지 않고 보드에서 가져옵니다. 패치 ID는 `devicetree-cfw-ipad_*`입니다. iPhone에서 사용하기 전에 이름이 정해졌기 때문입니다.
+- LLB는 디스플레이 배율 패치를 받지 않습니다. 반가상화 디스플레이의 부트 비디오 워드는 3x이며, 이는 이미 iPhone의 배율입니다.
+
+## 함께 보기
+
+- [iPadOS 게스트](ipados.md)
+- [펌웨어 호환성](compatibility.md)
+- [머신 생성 및 실행](../machines/create-and-run.md)
diff --git a/Documents/ko/get-started/downloads.md b/Documents/ko/get-started/downloads.md
new file mode 100644
index 00000000..15a58298
--- /dev/null
+++ b/Documents/ko/get-started/downloads.md
@@ -0,0 +1,86 @@
+# 다운로드
+
+내려받을 Launchpad 버전과 그에 맞는 `VPhone.bundle`을 고릅니다. 최신 릴리스에 공증된 Launchpad가 없거나 버전을 직접 맞춰야 할 때 이 페이지를 사용하세요.
+
+## 릴리스에 포함된 파일
+
+각 [릴리스](https://github.com/Lakr233/vphone-cli/releases)에는 최대 세 개의 파일이 있습니다.
+
+| 파일 | 내용 |
+| --- | --- |
+| `vphone-launchpad-<version>-notarized.zip` | Apple의 서명과 공증을 거친 Launchpad입니다. 있으면 이 파일을 내려받으세요. |
+| `vphone-launchpad-<version>.zip` | 공증되지 않은 Launchpad입니다. 처음 열 때 macOS가 차단합니다. |
+| `VPhone-<version>.zip` | `VPhone.bundle`입니다. Launchpad가 대신 내려받아 설치하므로 이 파일은 필요하지 않습니다. |
+
+공증되지 않은 버전을 열려면 한 번 연 뒤 **시스템 설정 > 개인정보 보호 및 보안**으로 이동하여 **그래도 열기**를 클릭합니다.
+
+## 공증된 Launchpad 버전
+
+| 시리즈 | 공증됨 | 공증되지 않음 |
+| --- | --- | --- |
+| 2.15 | 2.15.0 | 2.15.1 |
+| 2.14 | 2.14.0 | 2.14.1, 2.14.2 |
+| 2.13 | 2.13.0 | 2.13.1, 2.13.2, 2.13.3, 2.13.4, 2.13.5, 2.13.6, 2.13.7, 2.13.8 |
+| 2.12 | 2.12.0, 2.12.2 | 2.12.1 |
+| 2.11 | 2.11.0 | — |
+| 2.10 | 2.10.1 | — |
+| 2.9 | 2.9.0, 2.9.1, 2.9.2 | 2.9.3, 2.9.4, 2.9.5 |
+| 2.8 | 2.8.0 | — |
+| 2.7 | 2.7.0 | — |
+| 2.6 | 2.6.0 | 2.6.1 |
+| 2.5 | 2.5.0 | 2.5.1 |
+| 2.4 | 2.4.0, 2.4.1 | 2.4.2 |
+| 2.3 | 2.3.0 | 2.3.1, 2.3.2 |
+| 2.2 | 2.2.0, 2.2.2, 2.2.3, 2.2.4, 2.2.5 | 2.2.1 |
+| 2.1 | 2.1.0, 2.1.1, 2.1.2 | 2.1.3, 2.1.4, 2.1.5, 2.1.6, 2.1.7 |
+| 2.0 | 2.0.4, 2.0.5, 2.0.6, 2.0.8, 2.0.9 | — |
+
+2.0.7과 2.10.0 릴리스는 없습니다.
+
+## Launchpad와 VPhone.bundle 버전 맞추기
+
+Launchpad와 같은 시리즈의 `VPhone.bundle`을 사용하세요. 시리즈는 버전의 앞 두 숫자입니다. Launchpad 2.2.3은 2.2 시리즈에 속하며 모든 `VPhone.bundle` 2.2.x와 함께 동작합니다.
+
+| Launchpad | VPhone.bundle |
+| --- | --- |
+| 2.15.x | 2.15.x |
+| 2.14.x | 2.14.x |
+| 2.13.x | 2.13.x |
+| 2.12.x | 2.12.x |
+| 2.11.x | 2.11.x |
+| 2.10.x | 2.10.x |
+| 2.9.x | 2.9.x |
+| 2.8.x | 2.8.x |
+| 2.7.x | 2.7.x |
+| 2.6.x | 2.6.x |
+| 2.5.x | 2.5.x |
+| 2.4.x | 2.4.x |
+| 2.3.x | 2.3.x |
+| 2.2.x | 2.2.x |
+| 2.1.x | 2.1.x |
+| 2.0.x | 2.0.x |
+
+같은 시리즈 안에서는 가장 최신의 `VPhone.bundle`을 설치하세요. 패치 릴리스는 Launchpad와 번들이 함께 동작하는 방식을 바꾸지 않고 문제만 고칩니다.
+
+Launchpad는 자신에게 너무 오래된 `VPhone.bundle`은 거부하지만, 더 새로운 시리즈의 번들은 목록에 표시할 수 있습니다. 그런 번들은 설치하지 말고, 먼저 Launchpad를 해당 시리즈로 업데이트하세요.
+
+> [!NOTE]
+> Launchpad는 스스로 업데이트하지 않습니다. 릴리스 페이지에서 새 버전을 내려받아 기존 앱을 교체하세요.
+
+## 최근 시리즈에서 추가된 기능
+
+| 시리즈 | 추가된 기능 | 참고 |
+| --- | --- | --- |
+| 2.15 | HomeView | New Machine이 `HomeAccessory17,1`과 `HomeAccessory17,2`에 `homeview` 프리셋을 선택하도록 Launchpad 2.15를 같은 시리즈의 번들과 함께 사용하세요. |
+| 2.14 | 파일에서 패치 프리셋 불러오기: 프리셋 선택기의 **Other…** 또는 `--preset <path>` | Launchpad 2.14에는 2.14 번들이 필요합니다. |
+| 2.13 | Apple TV 4K(4세대) | New Machine이 `AppleTV18,1`에 `tvos-4k` 프리셋을 선택하도록 Launchpad 2.13을 같은 시리즈의 번들과 함께 사용하세요. |
+
+## 1.x 버전
+
+1.x에서 만든 가상 머신은 2.x에서 시작되지 않습니다. 1.x는 [1.0.14 릴리스](https://github.com/Lakr233/vphone-cli/releases/tag/1.0.14)를 참고하세요.
+
+## 함께 보기
+
+- [빠른 시작](quick-start.md)
+- [코어 번들](../launchpad/core-bundles.md)
+- [Launchpad 명령줄](../launchpad/launchpad-cli.md)
diff --git a/Documents/ko/get-started/host-setup.md b/Documents/ko/get-started/host-setup.md
new file mode 100644
index 00000000..d496a261
--- /dev/null
+++ b/Documents/ko/get-started/host-setup.md
@@ -0,0 +1,112 @@
+# 호스트 설정
+
+권한(entitlement)이 부여된 가상 머신 프로세스 `vphone-vm`을 실행할 수 있도록 Mac을 준비합니다. Mac마다 한 번만 하면 되며, 허용 목록 단계는 `vphone-vm`의 서명이 바뀔 때마다 반복합니다.
+
+macOS 15 이상을 실행하는 Apple Silicon Mac이 필요합니다. PV=3 연구용 게스트는 중첩된 macOS 가상 머신 안에서는 실행되지 않습니다.
+
+## 호스트 점검
+
+사용하는 `VPhone.bundle`에서 사전 점검을 실행합니다.
+
+```sh
+vphone-cli host preflight
+```
+
+가상 머신을 시작하기 전에 권한이 부여된 `vphone-vm`을 점검합니다. AMFI가 `vphone-vm`을 거부하면, 오류 메시지에 해당 번들에 맞는 `sudo .../vphone-escalator allow .../vphone-vm` 명령이 그대로 표시됩니다.
+
+## 보안 구성 선택
+
+`vphone-vm`에는 Apple 비공개 가상화 권한이 있으므로 macOS가 이를 허용해야 합니다. 아래 두 방법 모두 macOS 복구에서 Research Guests를 활성화해야 합니다. 하나를 선택하세요.
+
+### 방법 A: SIP를 유지하고 디버깅 제한만 완화
+
+1. macOS 복구로 시동하고 터미널을 열어 다음을 실행합니다.
+
+ ```sh
+ csrutil enable --without debug
+ csrutil allow-research-guests enable
+ ```
+
+2. macOS로 재시동합니다.
+3. 현재 `vphone-vm`을 허용 목록에 추가합니다. 배포된 번들이라면 `vphone-cli host preflight`를 실행하고 출력된 명령을 실행합니다. 소스 체크아웃에서는 다음과 같습니다.
+
+ ```sh
+ bundle=.build/XcodeBundle/Build/Products/Debug/VPhone.bundle
+ sudo "$bundle/Contents/MacOS/vphone-escalator" allow "$bundle/Contents/MacOS/vphone-vm"
+ "$bundle/Contents/MacOS/vphone-escalator" status
+ "$bundle/Contents/MacOS/vphone-cli" host preflight
+ ```
+
+> [!WARNING]
+> 빌드할 때마다 `allow` 명령을 다시 실행하세요. 서명만 바뀌는 재빌드도 마찬가지입니다. 허용 목록에는 `vphone-vm`의 cdhash가 저장되는데, 서명이 바뀌면 cdhash도 바뀝니다.
+
+허용 목록을 되돌리려면 다음을 실행합니다.
+
+```sh
+sudo "$bundle/Contents/MacOS/vphone-escalator" off
+```
+
+`off`는 `vphone-escalator`가 추가한 해시만 제거하고 amfid를 재시작합니다. 환경설정 자체와 그 밖의 값은 유지됩니다.
+
+제한된 권한이 필요한 다른 서명된 호스트 바이너리도 같은 `allow` 명령에 함께 넘길 수 있습니다. 권한이 없는 `vphone-cli`에는 필요하지 않습니다.
+
+### 방법 B: SIP와 AMFI 비활성화
+
+더 많은 것을 허용하는 구성입니다.
+
+1. macOS 복구로 시동하고 터미널을 열어 다음을 실행합니다.
+
+ ```sh
+ csrutil disable
+ csrutil allow-research-guests enable
+ ```
+
+2. macOS로 재시동하고 부트 인자를 설정한 뒤 다시 재시동합니다.
+
+ ```sh
+ sudo nvram boot-args="amfi_get_out_of_my_way=1 -v"
+ ```
+
+> [!WARNING]
+> 기존 `boot-args`를 덮어씁니다. 먼저 `nvram boot-args`로 확인하세요.
+
+## Launchpad를 사용할 때
+
+Launchpad의 번들 사전 점검은 SIP 디버깅 제한이 해제되었는지(또는 SIP가 완전히 꺼졌는지)와 Research Guests가 활성화되었는지 확인합니다. `vphone-escalator`를 직접 실행할 필요는 없습니다.
+
+- AMFI가 설치된 `vphone-vm`을 차단하면, Launchpad의 도우미가 해당 호스트 설정을 다시 확인하고, root 소유 번들과 기록된 cdhash를 검증한 뒤, 그 번들의 `vphone-escalator allow`를 root로 실행합니다. 그런 다음 Launchpad가 사전 점검을 다시 실행합니다.
+- 새 번들 서명은 각각 따로 확인하고 허용합니다.
+- 더 새로운 Launchpad에 더 새로운 도우미가 포함되어 있으면, 시작할 때 도우미를 업데이트하기 위해 관리자 인증을 요청합니다.
+
+단독으로 사용하는 `vphone-cli`는 여전히 직접 실행할 명령을 알려 줍니다.
+
+## 소스에서 빌드
+
+배포된 `VPhone.bundle`은 실행 시 Homebrew, Python, Xcode가 필요하지 않습니다. 소스에서 빌드하려면 `vphoned`를 컴파일할 Xcode와 iPhoneOS SDK가 필요합니다. 체크아웃에서 다음을 실행합니다.
+
+```sh
+xcodebuild -workspace VPhone.xcworkspace -scheme VPhone \
+ -configuration Debug -destination 'platform=macOS,arch=arm64' \
+ -derivedDataPath .build/XcodeBundle build
+.build/XcodeBundle/Build/Products/Debug/VPhone.bundle/Contents/MacOS/vphone-cli host preflight
+```
+
+`VPhone` 스킴은 모든 프로그램이 포함된, 애드혹 서명된 번들을 만듭니다. 방법 A를 사용한다면 새로 빌드할 때마다 허용 목록에 추가하세요.
+
+## 허용 목록이 변경하는 것
+
+`vphone-escalator allow`는 AMFI 코드 요구 사항 환경설정이 없으면 새로 만듭니다. 이미 있으면 그 `Entitlements` 요구 사항에 현재 `vphone-vm`의 cdhash를 추가하며, 다른 cdhash와 환경설정 키는 유지하고 이미 있는 해시는 건너뜁니다. 기존 `AllowUnsafeDynamicLinking` 값은 건드리지 않으며, 그 키가 없을 때만 `false`를 기록합니다. amfid의 힙에서 1바이트를 바꿔 amfid가 이 요구 사항을 참조하도록 합니다.
+
+## 번들에 포함된 것
+
+- `vphone-cli`는 비공개 권한 없이 작업 전체를 조율하며, `vphone-cli archive`로 아카이브를 처리합니다.
+- `vphone-vm`은 서명되고 권한이 부여된 가상 머신 및 창 프로세스입니다.
+- `vphoned`는 빌드 시 iOS용으로 컴파일되며, 생성되는 각 게스트에 설치됩니다.
+
+구현 경위는 [바이너리 분리에 관한 연구 기록](../../../Research/Host/host_binary_split.md)을 참고하세요.
+
+## 함께 보기
+
+- [빠른 시작](quick-start.md)
+- [가상 머신 생성 및 실행](../machines/create-and-run.md)
+- [문제 해결](../help/troubleshooting.md)
diff --git a/Documents/ko/get-started/overview.md b/Documents/ko/get-started/overview.md
new file mode 100644
index 00000000..07a7f40d
--- /dev/null
+++ b/Documents/ko/get-started/overview.md
@@ -0,0 +1,50 @@
+# 개요
+
+vphone-cli는 Apple Silicon Mac에서 가상 iPhone을 실행합니다. 이 페이지에서는 vphone-cli가 하는 일, Mac에 필요한 조건, 각 프로그램의 역할을 설명합니다.
+
+> [!WARNING]
+> 본 프로젝트는 암호화폐나 토큰을 발행하거나 그 발행을 승인한 적이 없으며, 암호화폐 결제나 기부도 받지 않습니다. 본 프로젝트의 이름을 내세워 발행·홍보하거나 본 프로젝트와의 관련성을 주장하는 암호화폐와 토큰은 모두 사기입니다.
+
+![macOS에서 실행 중인 가상 iPhone](../../demo.jpeg)
+
+vphone-cli는 Apple의 Virtualization.framework와 PCC 연구용 가상 머신으로 iOS를 실행하며, 보안 연구, 리버스 엔지니어링, 디버깅에 사용합니다.
+
+## 기능
+
+- **그래픽 창:** Mac에서 가상 iPhone의 화면을 조작하고, 앱과 파일을 탐색하며, 스크린샷을 찍고 화면을 녹화합니다.
+- **커스텀 펌웨어:** 시스템에 패치가 미리 적용되어 있으며, [패키지 환경](../machines/package-environment.md)을 설치할 수 있습니다.
+- **백업과 복제:** 가상 머신을 내보내고, 가져오고, 복제합니다.
+- **자동화 API:** 선택적으로 사용할 수 있는 로컬 HTTP 및 WebSocket 인터페이스입니다. [자동화 API](../machines/automation-api.md)를 참고하세요.
+- **추가 의존성 없음:** 실행에 Xcode, Python, Homebrew가 필요하지 않습니다.
+
+## 준비 사항
+
+- macOS 15 이상을 실행하는 물리 Apple Silicon Mac. macOS 가상 머신에서는 동작하지 않습니다.
+- 여유 디스크 공간. 가상 머신마다 기본적으로 64 GB 가상 디스크를 사용하며, 펌웨어가 별도로 공간을 차지합니다.
+- 네트워크 연결. 시스템을 복원할 때 서명 티켓을 온라인으로 받습니다.
+- 보안 설정 변경. macOS 복구로 시동하고 터미널에서 다음 명령을 실행한 뒤 재시동합니다.
+
+ ```sh
+ csrutil enable --without debug
+ csrutil allow-research-guests enable
+ ```
+
+ SIP는 켜진 상태로 유지되며 디버깅 제한만 완화됩니다. 자세한 내용은 [호스트 설정](host-setup.md)을 참고하세요.
+
+## 네 가지 프로그램
+
+| 프로그램 | 역할 |
+| --- | --- |
+| `vphone-launchpad` | `VPhone.bundle`을 내려받아 설치하고 호스트를 설정하는 Mac 앱입니다. 별도로 배포됩니다. |
+| `vphone-cli` | 펌웨어를 준비하고 패치하며, 시스템을 복원하고 가상 머신을 관리합니다. |
+| `vphone-vm` | 가상 머신을 실행하고 그 창을 표시합니다. |
+| `vphoned` | 가상 머신 안의 제어 서비스입니다. 창의 기능과 API가 이를 통해 동작합니다. |
+
+`vphone-cli`, `vphone-vm`, `vphoned`는 `VPhone.bundle`에 함께 포함되어 배포됩니다. Launchpad는 이 번들 안의 `vphone-cli`로 각 가상 머신을 제어하며, 터미널에서 `vphone-cli`를 직접 실행할 수도 있습니다.
+
+## 함께 보기
+
+- [빠른 시작](quick-start.md)
+- [호스트 설정](host-setup.md)
+- [다운로드](downloads.md)
+- [가상 머신 생성 및 실행](../machines/create-and-run.md)
diff --git a/Documents/ko/get-started/quick-start.md b/Documents/ko/get-started/quick-start.md
new file mode 100644
index 00000000..3fe8d4c5
--- /dev/null
+++ b/Documents/ko/get-started/quick-start.md
@@ -0,0 +1,41 @@
+# 빠른 시작
+
+Launchpad로 vphone을 설정하고 첫 가상 iPhone을 부팅합니다. Mac이 [준비 사항](overview.md)을 갖춘 뒤에 진행하세요.
+
+## Launchpad로 설정하기
+
+1. [최신 릴리스](https://github.com/Lakr233/vphone-cli/releases/latest)에서 `vphone-launchpad-<version>-notarized.zip`을 내려받아 압축을 풀고 엽니다. 모든 릴리스가 공증된 것은 아닙니다. 최신 릴리스에 `-notarized` 파일이 없으면 [다운로드](downloads.md)에서 공증된 버전을 선택하세요.
+2. **Host Setup**(호스트 설정)에서 개발자 도구 접근 권한을 부여하고 도우미를 설치합니다.
+3. **Core Bundle**(코어 번들)에서 **Download and Install**(다운로드 및 설치)을 클릭합니다.
+4. **Machines**(머신)에서 **New Machine**(새 머신)을 클릭하고 펌웨어 조합을 선택한 뒤 **Create**(생성)를 클릭합니다.
+
+Launchpad가 펌웨어를 내려받고, 패치를 적용하고, 시스템을 복원한 뒤 가상 머신을 부팅합니다. 직접 준비한 iPhone 및 cloudOS IPSW를 사용하려면 [호환성](../firmware/compatibility.md)을 참고하세요.
+
+## 에이전트에게 맡기기
+
+이 Mac에서 코딩 에이전트(Claude Code, Codex 등)를 사용한다면 직접 단계를 따라 하는 대신 아래 프롬프트를 붙여 넣으세요. 에이전트는 vphone 스킬을 읽고, 이미 설정된 부분을 확인한 뒤 Launchpad와 `VPhone.bundle`을 설치합니다. 관리자 암호나 macOS 복구에서의 변경처럼 사용자가 해야 하는 단계에서는 멈추고 물어봅니다.
+
+```text
+이 Mac에 vphone을 설정해 주세요. 먼저 다음 스킬을 읽으세요:
+https://raw.githubusercontent.com/Lakr233/vphone-cli/main/Skills/vphone-guest-control/SKILL.md
+그리고 같은 폴더의 references/ 아래에 링크된 파일을 읽고 그대로 따라 하세요:
+공증된 최신 vphone-launchpad를 설치하고(모든 릴리스에 -notarized zip이 있는 것은
+아닙니다), vphone-launchpad-cli를 PATH에 추가하고, Launchpad와 같은 시리즈의
+VPhone.bundle을 설치한 뒤 `vphone-launchpad-cli status`로 확인하세요. SIP,
+boot-args 등 호스트 보안 설정은 변경하지 말고, 펌웨어와 여유 디스크 공간을
+제가 확인하기 전에는 머신을 만들지 마세요. 제가 해야 하는 단계에서는 무엇을
+해야 하는지 정확히 알려 주고 기다리세요.
+```
+
+## 다음 단계
+
+- 가상 머신에 패키지 관리자 설치하기: [패키지 환경](../machines/package-environment.md)
+- 터미널에서 가상 머신을 제어하거나 Launchpad 없이 만들기: [가상 머신 생성 및 실행](../machines/create-and-run.md)
+- HTTP와 WebSocket으로 가상 머신을 스크립트로 제어하기: [자동화 API](../machines/automation-api.md)
+- 문제가 생겼을 때: [문제 해결](../help/troubleshooting.md)
+
+## 함께 보기
+
+- [호스트 설정](host-setup.md)
+- [다운로드](downloads.md)
+- [Launchpad 명령줄](../launchpad/launchpad-cli.md)
diff --git a/Documents/ko/help/troubleshooting.md b/Documents/ko/help/troubleshooting.md
new file mode 100644
index 00000000..cbe4b3d6
--- /dev/null
+++ b/Documents/ko/help/troubleshooting.md
@@ -0,0 +1,52 @@
+# 문제 해결
+
+보이는 증상이나 오류 메시지를 찾은 뒤 그 아래의 해결 방법을 따르세요. 네트워크 문제는 [네트워크](../networking/overview.md)를 참고하세요.
+
+## 가상 머신이 열리기 전에 `vphone-vm`이 종료됨
+
+1. 호스트 사전 점검을 실행합니다.
+
+ ```sh
+ vphone-cli host preflight
+ ```
+
+ CLI에는 권한이 없으므로 계속 실행되며, 서명된 짝 프로그램 `vphone-vm`을 AMFI가 거부한 이유를 설명할 수 있습니다.
+2. 번들을 다시 빌드했다면 cdhash가 바뀐 것입니다. [호스트 설정](../get-started/host-setup.md)에 설명된 대로 번들에 포함된 도우미로 새 바이너리를 허용하세요.
+
+## `Virtualization is not available on this hardware`
+
+PV=3 게스트는 중첩할 수 없습니다. 다른 macOS 가상 머신 안이 아니라 Apple Silicon Mac에서 실행하세요.
+
+## `vm create`가 vphoned 성공을 출력했지만 실행 중인 가상 머신이 없음
+
+정상입니다. 생성 과정은 임시 GUI 부팅을 시작해 실제 ping을 보낸 뒤, 반환하기 전에 그 부팅을 중지합니다. 사용하려면 가상 머신을 시작하세요.
+
+```sh
+vphone-cli vm launch <name>
+```
+
+## "Press home to continue"에서 멈춤
+
+가상 머신 창의 제목 막대에 있는 홈 버튼을 클릭하세요. 현재 JB 작업 흐름은 VNC 서버를 설치하지 않습니다.
+
+## 앱이 `EXC_GUARD` / `GUARD_TYPE_MACH_PORT`로 종료됨
+
+커널 패치 `kernel-boot-thread_guard_violation`은 치명적인 Mach 포트 가드 전달을 막습니다. 이 패치는 부팅에 필요한 iOS 18 기반에서만 적용되며, 그곳에서는 모든 프리셋이 이를 켭니다. 다른 기반에서는 선택할 수 없으므로, 26.x 기반에서 이 가드에 걸리는 앱은 여전히 종료됩니다. [이슈 #291](https://github.com/Lakr233/vphone-cli/issues/291)을 참고하세요.
+
+## 복원 또는 첫 부팅 실패
+
+- 수동 흐름에서는 `restore`가 끝날 때까지 가상 머신을 DFU 상태로 유지하세요.
+- 온라인 티켓 요청이 Apple에 도달할 수 있는지 확인하세요.
+- 전체 파이프라인은 **새 이름**과 도구 세부 정보를 위한 `-v`로 `vm create`를 다시 실행하세요.
+- 메모리나 디스크가 부족하면 가상 머신을 동시에 여러 개 만들지 마세요.
+- iPhone IPSW와 PCC 이미지를 조합하기 전에 [펌웨어 호환성](../firmware/compatibility.md)을 확인하세요.
+
+## 게스트는 부팅되지만 생성 중에 vphoned가 응답하지 않음
+
+첫 부팅 확인은 300초 후 시간 초과됩니다. 새로 복원한 게스트는 첫 헤드리스 부팅에서 vphoned를 띄우지 못할 수 있으므로, 생성 과정에서는 GUI 부팅을 사용합니다. 성공 표시가 무엇을 확인하는지는 [생성 및 실행](../machines/create-and-run.md)을 참고하세요.
+
+## 함께 보기
+
+- [호스트 설정](../get-started/host-setup.md)
+- [생성 및 실행](../machines/create-and-run.md)
+- [펌웨어 호환성](../firmware/compatibility.md)
diff --git a/Documents/ko/launchpad/bundle-integration.md b/Documents/ko/launchpad/bundle-integration.md
new file mode 100644
index 00000000..a5b827ee
--- /dev/null
+++ b/Documents/ko/launchpad/bundle-integration.md
@@ -0,0 +1,59 @@
+# VPhone 번들 통합
+
+이 페이지는 `vphone-launchpad`처럼 `VPhone.bundle`을 포함해 배포하거나 제어하는 애플리케이션을 만드는 사람을 위한 것입니다. 번들에 무엇이 들어 있고, 통합하는 애플리케이션이 무엇을 책임지는지 설명합니다.
+
+## 빌드 및 검증
+
+```sh
+xcodebuild -workspace VPhone.xcworkspace -scheme VPhone \
+ -configuration Debug -destination 'platform=macOS,arch=arm64' \
+ -derivedDataPath .build/XcodeBundle build
+```
+
+`VPhone` 스킴은 `VPhone.bundle`을 만들며, 빌드 과정에서 `ValidateBundle.sh`가 이를 검사합니다.
+
+## 통합 방법
+
+- 번들을 그대로 유지하고 `Contents/MacOS/vphone-cli`를 프로세스로 실행하세요. 번들은 실행 파일과 리소스를 담는 컨테이너이며, macOS 앱이나 동적으로 로드되는 플러그인이 아닙니다. CLI는 자신의 실행 파일 경로를 기준으로 짝이 되는 `vphone-vm`을 찾습니다.
+- 번들 전체를 버전이 매겨진 하나의 단위로 설치하고 업데이트하세요. 서명된 바이너리를 그 자리에서 다시 쓰지 마세요.
+- `vphone-vm`이 바뀌면 cdhash도 바뀝니다. 새 빌드를 실행하기 전에 AMFI 허용을 준비하세요.
+- 다운로드, 릴리스 검증, 호스트 인증, 설치, 업데이트 정책은 애플리케이션이 담당합니다. 개발자 도구 접근 권한과 AMFI 인증은 서로 별개인 호스트 결정입니다.
+- 가상 머신 보관함과 캐시는 `VPhone.bundle` 밖, 기본적으로 `~/.vphone` 아래에 있습니다. 호스트 쪽 가상 머신 출력물은 root로 실행한 생성 작업 후에도 별도의 워크스테이션 프로세스가 접근할 수 있도록 `0777` 모드를 사용합니다. `Disk.img` 안의 게스트 파일 시스템 권한은 고유의 의미를 유지합니다.
+
+## 번들 내용
+
+| 경로 | 역할 |
+| --- | --- |
+| `Contents/MacOS/vphone-cli` | 권한이 없는 명령 진입점 |
+| `Contents/MacOS/vphone-vm` | 가상 머신 및 창 프로세스. 비공개 가상화 권한 보유 |
+| `Contents/MacOS/vphone-escalator` | 현재 가상 머신 cdhash를 위한 AMFI 허용 목록 도구 |
+| `Contents/MacOS/libswiftCompatibilitySpan.vphone.dylib` | macOS 15에서 `vphone-vm`이 사용하는 Swift 백디플로이먼트 라이브러리 |
+| `Contents/Resources/guest-resources/vphoned` | 자체 권한으로 미리 서명된 게스트 데몬. 번들에 서명되지 않은 사본은 없습니다 |
+| `Contents/Resources/guest-resources/*.dylib` | 게스트 라이브러리: launchd 훅, SystemHook, 카메라 훅, GPU 컴파일러 플러그인, 그리고 [`VPhoneGuestComponents`](../../../VPhoneGuestComponents/README.md)에 나열된 수정 사항과 기기 어댑터 |
+| `Contents/Resources/guest-resources/*.plist` | 게스트 launch daemon 구성, 카메라 훅 및 MISFix 필터 |
+| `Contents/Resources` | 현지화된 문자열. 서명 스크립트나 권한 파일은 포함되지 않습니다 |
+
+`Contents/MacOS`에는 Mac에서 실행되는 프로그램만 있습니다. `guest-resources`에는 게스트에 설치되는 파일만 있으며, 그 안의 모든 Mach-O는 iOS용으로 빌드됩니다. `ValidateBundle.sh`가 두 규칙을 모두 강제합니다.
+
+## 서명
+
+모든 실행 파일은 애드혹 코드 서명을 사용합니다. 비공개 권한은 그것이 필요한 하위 프로세스에만 있습니다. 번들에는 `CFBundleExecutable`, 앱 실행기, SMJobBless 도우미, 설치 프로그램, 암호 입력 창, 자동 root 획득 기능이 없습니다.
+
+## 개인정보 보호 권한
+
+macOS는 책임 프로세스(responsible process)를 대신해 개인정보 보호 권한(마이크, 위치)을 요청하고, 허용 여부를 그 프로세스의 코드 서명에 연결합니다.
+
+- 책임을 포기(disclaim)한 상태로 `vphone-cli`를 시작하면 `vphone-cli`가 `vphone-vm`의 책임 프로세스가 됩니다. 애드혹으로 서명되어 있으므로, 번들을 새로 빌드할 때마다 다시 요청합니다.
+- 서명이 안정된 프로세스의 일반 하위 프로세스로, 책임을 포기하지 않고 `vphone-cli`를 시작하면 권한을 한 번만 요청합니다.
+
+Launchpad는 자신의 `Contents/MacOS`에 포함된 `vphone-launchpad-launcher`로 두 번째 방식을 사용합니다. macOS는 그 위치의 도구를 감싸는 앱에 귀속시키므로, 요청 창, 사용 목적 설명, 허용은 모두 앱의 것이 됩니다. 강화된 런타임에서는 앱의 주 실행 파일에 해당 리소스 권한(`com.apple.security.device.audio-input`, `com.apple.security.personal-information.location`)이 있어야 하며, 없으면 macOS가 묻지 않고 요청을 거부합니다.
+
+## 버전 호환성
+
+Launchpad는 `minimumBundleComponents`([`VPhoneLaunchpad/VPhoneLaunchpadShared/VPhoneLaunchpadBundleStore.swift`](../../../VPhoneLaunchpad/VPhoneLaunchpadShared/VPhoneLaunchpadBundleStore.swift)에서 설정)보다 오래된 번들을 거부하며, 이전 번들 레이아웃은 로드하지 않습니다. 번들 2.1.0에서 패치 프리셋(`fw patches`, `fw set-patches`, `fw patch --preset`)과 `vphone-escalator` 실행 파일이 추가되었습니다.
+
+## 함께 보기
+
+- [코어 번들과 로컬 빌드](core-bundles.md)
+- [Launchpad 명령줄](launchpad-cli.md)
+- [호스트 설정](../get-started/host-setup.md)
diff --git a/Documents/ko/launchpad/core-bundles.md b/Documents/ko/launchpad/core-bundles.md
new file mode 100644
index 00000000..ee0dc079
--- /dev/null
+++ b/Documents/ko/launchpad/core-bundles.md
@@ -0,0 +1,104 @@
+# 코어 번들과 로컬 빌드
+
+Launchpad의 각 머신은 설치된 `VPhone.bundle` 버전 하나, 즉 코어 번들(Core Bundle)로 실행됩니다. 이 페이지에서는 로컬 빌드를 설치하고, 머신을 그 빌드로 옮기고, 두 빌드를 나란히 비교하는 방법을 설명합니다.
+
+## VPhone.bundle 빌드 테스트하기
+
+1. 저장소 루트에서 번들을 빌드합니다.
+
+ ```sh
+ xcodebuild -workspace VPhone.xcworkspace -scheme VPhone \
+ -configuration Debug -destination 'platform=macOS,arch=arm64' \
+ -derivedDataPath .build/XcodeBundle build
+ ```
+
+2. 설치합니다. `<version>-local.<hash>`로 설치되어 기본 번들이 되고, 실행 정책 예외를 받고, 새 `vphone-vm` cdhash가 허용되며, 호스트 사전 점검이 실행됩니다.
+
+ ```sh
+ vphone-launchpad-cli bundle install-local .build/XcodeBundle/Build/Products/Debug/VPhone.bundle
+ ```
+
+ 정확한 버전은 설치 결과와 `bundle list`에 표시됩니다.
+
+3. 기존 머신을 그 빌드로 옮깁니다. `--update-environment`는 새 vphoned와 훅 dylib도 다시 배포하며, 머신이 중지되어 있어야 합니다.
+
+ ```sh
+ vphone-launchpad-cli vm set-bundle research-01 2.4.0-local.1a2b3c4d --update-environment
+ ```
+
+4. 머신을 시작하고 확인합니다.
+
+ ```sh
+ vphone-launchpad-cli vm start research-01 --wait
+ vphone-launchpad-cli guest rpc research-01 device.info
+ vphone-launchpad-cli guest rpc research-01 apps.list '{}'
+ vphone-launchpad-cli vm log research-01 --lines 100
+ vphone-launchpad-cli vm stop research-01
+ ```
+
+도우미의 인증은 5분 동안 유지됩니다. 만료된 뒤 도우미가 필요한 첫 단계에서는 창에서와 마찬가지로 Mac에서 관리자 암호를 묻습니다.
+
+기존 가상 머신에서 영구 셰이더 캐시를 활성화하기 위한 일회성 커널 및 게스트 업데이트는 [영구 셰이더 캐시](../storage/shader-cache.md)를 참고하세요.
+
+## 두 빌드 비교하기
+
+기본 번들을 바꾸지 않고 둘 다 설치한 뒤, 각각에 머신을 하나씩 지정합니다.
+
+```sh
+vphone-launchpad-cli bundle install-local /path/to/A/VPhone.bundle --keep-default
+vphone-launchpad-cli bundle install-local /path/to/B/VPhone.bundle --keep-default
+vphone-launchpad-cli bundle list # note both versions
+
+vphone-launchpad-cli vm create cmp-a --bundle 2.4.0-local.aaaaaaaa
+vphone-launchpad-cli vm create cmp-b --bundle 2.4.0-local.bbbbbbbb
+```
+
+이렇게 만든 머신은 세 계층 모두가 다릅니다(아래 참고). 같은 부트 체인에서 호스트 프로그램과 게스트 환경만 비교하려면, 창에서 머신을 복제하고 사본을 다른 번들에 다시 연결하세요.
+
+```sh
+vphone-launchpad-cli vm set-bundle cmp-b 2.4.0-local.bbbbbbbb --update-environment
+```
+
+`vm list`는 각 계층이 어느 번들에서 왔는지 표시합니다. `bundle remove`는 머신이 연결된 버전을 거부하므로, 먼저 그 머신을 다른 번들에 연결하거나 삭제하세요.
+
+## 머신이 번들에 연결되는 방식
+
+모든 머신은 설치된 버전 하나에 연결됩니다. 이 버전은 생성할 때 선택되며 머신 폴더의 `launchpad.json`에 저장됩니다. 번들을 설치해도 머신의 연결은 바뀌지 않습니다.
+
+머신은 세 계층으로 이루어지며, 각 계층은 서로 다른 시점에 번들에서 가져옵니다.
+
+| 계층 | 내용 | 출처 |
+| --- | --- | --- |
+| Host Programs(호스트 프로그램) | `vphone-cli`, `vphone-vm` | 명령을 실행할 때마다 연결된 번들에서. 새 연결은 다음 시작부터 적용됩니다. |
+| Guest Environment(게스트 환경) | vphoned와 훅 dylib | 생성 시 `cfw install`, 이후에는 `cfw update-environment`(중지된 머신). |
+| Boot Chain(부트 체인) | 패치된 펌웨어, 복원, CFW 패치 | 생성 시 `fw patch`, `restore`, `cfw install`. |
+
+### 나중에 부트 체인 패치 변경하기
+
+`vphone-cli fw set-patches`로 패치 선택을 바꾸고, `vphone-cli fw patches <vm>`으로 아직 게스트에 반영되지 않은 항목을 확인합니다. Launchpad는 인스펙터에 그 개수를 표시합니다. 패치 종류마다 게스트에 반영되는 방식이 다릅니다.
+
+| 패치 | 적용 방법 |
+| --- | --- |
+| 게스트 패치 | 다음 `cfw update-environment` |
+| AVPBooter | 다음 `fw patch` |
+| 커널 패치 | `cfw update-kernel`(데이터 유지, 복원 트리 불필요) |
+| 나머지 부트 체인(TXM, DeviceTree, LLB) | 게스트를 지우는 복원으로만 가능 |
+
+## 기본 번들
+
+**default**(기본) 번들(이전 이름 "active")이 결정하는 것은 다음뿐입니다.
+
+- `--bundle`을 지정하지 않았을 때 `vm create`가 연결할 버전
+- `exec`와 보관함 전체에 적용되는 명령이 실행될 번들
+
+`--keep-default`를 넘기지 않으면 새로 설치한 번들이 기본 번들이 됩니다. Launchpad 세션에서 머신을 처음 시작할 때 번들을 한 번 확인합니다(실행 정책 예외, AMFI, 호스트 사전 점검).
+
+## 버전 이름
+
+로컬 빌드는 `<version>-local.<hash>`로 설치되며, 해시는 번들의 코드 서명 봉인에서 가져오므로 같은 버전의 두 빌드가 나란히 존재할 수 있습니다. 이전 저장소에는 `<version>-local`이나 `<version>-ci.<commit>`이 남아 있을 수 있습니다.
+
+## 함께 보기
+
+- [Launchpad 명령줄](launchpad-cli.md)
+- [번들 통합](bundle-integration.md)
+- [다운로드](../get-started/downloads.md)
diff --git a/Documents/ko/launchpad/launchpad-cli.md b/Documents/ko/launchpad/launchpad-cli.md
new file mode 100644
index 00000000..59c32fff
--- /dev/null
+++ b/Documents/ko/launchpad/launchpad-cli.md
@@ -0,0 +1,180 @@
+# Launchpad 명령줄
+
+`vphone-launchpad-cli`는 터미널이나 스크립트에서 실행 중인 Launchpad를 제어합니다. 번들을 설치하고, 머신을 만들고 시작하고 중지하며, 게스트와 통신합니다. 창을 일일이 클릭하지 않고 Launchpad의 동작을 이용하고 싶을 때 사용하세요.
+
+## 설정하기
+
+CLI는 `vphone-launchpad.app/Contents/MacOS`에 포함되어 있습니다. `PATH`에 링크하세요.
+
+```sh
+ln -s /Applications/vphone-launchpad.app/Contents/MacOS/vphone-launchpad-cli /usr/local/bin/
+vphone-launchpad-cli help
+```
+
+Launchpad가 실행 중이 아니면 CLI가 Launchpad를 시작합니다. CLI가 시작한 Launchpad는 숨겨진 상태로 열리며, 앞에 있는 앱의 포커스를 가져가지 않습니다. 창을 보려면 Dock 아이콘이나 메뉴 막대의 Open Launchpad를 클릭하세요. 창을 앞으로 띄운 상태로 시작하려면 `--foreground`를 넘깁니다(명령 앞, 또는 `exec`를 제외한 모든 명령의 옵션 사이). 어느 쪽도 이미 실행 중인 Launchpad에는 영향을 주지 않습니다.
+
+## 출력과 종료 상태
+
+- 진행 상황은 도착하는 대로 stderr에 출력됩니다.
+- 결과는 stdout에 JSON 문서 하나로 출력됩니다.
+- 종료 상태는 성공 시 0, 실패 시 1이며, 이유는 stderr에 출력됩니다.
+- CLI를 중단하면 취소할 수 있는 명령(`exec`, 대기, CFW 설치)은 취소됩니다. 번들 설치와 머신 생성은 창에 속하므로 계속 실행됩니다.
+
+모든 명령은 Launchpad의 창과 명령 기록에도 표시됩니다.
+
+## 명령
+
+두 보관함에 같은 이름의 머신이 있을 때 머신 명령은 `--root <library>`를 받습니다.
+
+### 상태와 번들
+
+| 명령 | 동작 |
+| --- | --- |
+| `status` | 호스트 점검, 도우미, 기본 번들, 머신 수 |
+| `bundle list` | 설치된 버전, 영수증, cdhash, 점검 결과, 연결된 머신 |
+| `bundle install-local <path> [--keep-default]` | 로컬 `VPhone.bundle` 폴더 또는 `.zip` 설치 |
+| `bundle install-release <version\|latest> [--keep-default]` | GitHub 릴리스를 내려받아 설치 |
+| `bundle set-default <version>` | 버전을 기본으로 지정. `bundle use`는 이전 이름입니다 |
+| `bundle verify <version>` | 버전을 다시 점검 |
+| `bundle accept <version> [--off]` | 실패한 점검을 건너뛰거나, `--off`로 건너뛰기를 중단 |
+| `bundle remove <version>` | 연결된 머신이 없는 버전 제거 |
+
+로컬 빌드를 설치하거나, 머신을 그 빌드로 옮기거나, 두 빌드를 비교하려면 [코어 번들과 로컬 빌드](core-bundles.md)를 참고하세요.
+
+### 머신
+
+| 명령 | 동작 |
+| --- | --- |
+| `vm list` | 모든 보관함의 머신과 실행 상태, Core Bundle, 로그 경로 |
+| `vm start <name> [--headless] [--wait]` | 머신의 번들로 시작. `--wait`는 vphoned를 기다립니다 |
+| `vm stop <name>` | 게스트에 종료를 요청하고(vphoned `system.shutdown`) 최대 30초 기다립니다. 게스트에 요청할 수 없거나 멈추지 않으면 가상 머신을 종료합니다 |
+| `vm wait <name>` | vphoned를 기다립니다 |
+| `vm log <name> [--lines <n>] [--kind create\|dfu\|patch]` | 콘솔 로그 읽기 |
+| `vm create <name> [options]` | New Machine 파이프라인. 아래의 '머신 만들기'를 참고하세요 |
+| `vm set-bundle <name> <version> [--update-environment]` | 머신을 설치된 다른 버전에 연결 |
+| `vm leases [--release]` | 공유 NAT 네트워크의 DHCP 임대와 각 임대를 소유한 머신. `--release`는 어느 보관함의 머신도 사용하지 않는 임대를 도우미를 통해 해제합니다([MAC 및 IP 주소](../networking/addresses.md)의 '이전 MAC이 차지하고 있는 주소' 참고) |
+
+참고:
+
+- `vm list`에서 머신을 `running`으로 만드는 것은 디스크를 붙잡고 있는 가상 머신 프로세스(`vphone-vm` 또는 Virtualization의 가상 머신 서비스)뿐입니다. 디스크를 열고 있는 다른 프로세스(`tail`, Spotlight, 백업 도구)는 `diskOpenIn`에 표시되며(예: `12925 tail`), 머신은 `stopped`로 남습니다.
+- `vm start`는 `vphone-cli vm launch`와 마찬가지로 디스크를 열고만 있는 프로세스 때문에 거부되지 않으며, 그 프로세스의 이름을 담은 메모를 출력합니다.
+- `vm start --wait`와 `vm wait`는 `--timeout`도 받습니다.
+- `vm set-bundle --update-environment`는 해당 버전의 게스트 환경도 다시 배포하며, 머신이 중지되어 있어야 합니다. 다른 프로세스가 디스크를 열고 있으면 연결을 바꾸기 전에 그 프로세스의 이름을 표시하며 거부합니다. 업데이트 자체가 실패하면 머신은 새 버전에 연결된 상태로 남고 `vm list`는 여전히 이전 `guestEnvironmentBundle`을 표시합니다. 마무리하려면 `cfw update-environment`를 실행하세요.
+
+### CFW
+
+이 명령들은 중지된 머신에서 머신 자체의 번들로, Launchpad의 도우미를 통해 실행됩니다. 다른 프로세스가 디스크를 열고 있으면 그 이름(`12925 tail`)을 표시하며 거부합니다.
+
+| 명령 | 동작 |
+| --- | --- |
+| `cfw install <name>` | CFW 설치. 해당하는 경우 도우미가 임시 작업 파일을 가상 머신 보관함의 외장 볼륨에 둡니다 |
+| `cfw update-environment <name>` | 번들의 게스트 리소스(vphoned, 훅 dylib)를 다시 배포. 그 밖에는 아무것도 바뀌지 않습니다 |
+| `cfw update-kernel <name>` | 머신의 현재 패치 선택으로 kernelcache를 다시 패치하고 Preboot에서 교체하며, 데이터는 유지합니다. 설치된 가상 머신에서 데이터를 유지하며 커널 패치를 바꾸는 방법이며, 복원 트리가 필요하지 않습니다 |
+
+### 게스트
+
+`guest` 명령과 `--wait`는 모든 시작에서 제공되는 머신의 `vphone.sock`을 통해 동작합니다. 2.0.9 이하의 번들은 창과 함께 시작한 머신에서만 이를 제공합니다.
+
+| 명령 | 동작 |
+| --- | --- |
+| `guest send <name> <json>` | 원시 `vphone.sock` 요청 하나(tap, swipe, key, screenshot) |
+| `guest rpc <name> <method> [params]` | 모든 vphoned 메서드. [`Research/vphoned_http_api.md`](../../../Research/vphoned_http_api.md)를 참고하세요. vphoned가 거부하면 stderr의 마지막 줄이 JSON 형식의 오류 객체입니다(`code`, `message`, `results`, `reason` …) |
+| `guest push <name> <local> <guest-path> [--mode <octal>]` | Mac의 파일을 게스트로 복사. vphoned를 통해 스트리밍하므로 `guest rpc`의 1 MiB JSON 한 줄 제한을 받지 않습니다. 바이너리와 IPA에 사용하세요. `/`로 끝나는 게스트 경로는 파일 이름을 유지하며, 모드의 기본값은 Mac 파일의 권한입니다 |
+| `guest pull <name> <guest-path> <local>` | 게스트 파일을 Mac으로 스트리밍 복사. `local`은 폴더여도 됩니다. 파일은 완료된 뒤에만 `local`을 대체합니다 |
+| `guest unlock <name> [--passcode <code>] [--timeout <seconds>]` | 어떤 상태였든 화면을 켜고 게스트의 잠금을 해제합니다(vphoned `screen.unlock`). `--passcode`는 게스트에 암호가 있을 때만 필요합니다 |
+
+### vphone-cli 실행
+
+| 명령 | 동작 |
+| --- | --- |
+| `exec [--bundle <version>] <vphone-cli arguments>` | 기본 번들 또는 지정한 버전의 `vphone-cli`를 실행하고 출력을 스트리밍합니다. `--bundle`은 맨 앞에 와야 합니다 |
+
+## 머신 만들기
+
+`vm create`는 `--bundle <version>` 또는 기본 번들에 연결하여 New Machine 파이프라인을 실행합니다. 머신은 템플릿에서 복제되며, 템플릿이 없으면 먼저 빌드합니다(2.9). `--no-template`이면 단독으로 복원합니다.
+
+```sh
+vphone-launchpad-cli vm create rt-e --block system-debugserver-cfw-install
+```
+
+| 옵션 | 동작 |
+| --- | --- |
+| `--bundle <version>` | 기본 번들 대신 설치된 이 버전에 머신을 연결 |
+| `--device <product-type>` | 다른 기기 만들기. 아래의 '다른 기기'를 참고하세요 |
+| `--preset <preset>` | 프리셋 이름 또는 프리셋 plist 경로(2.14). 머신이 그 사본을 보관합니다 |
+| `--block <patch>`, `--allow <patch>` | 프리셋의 패치 하나를 끄거나 켭니다. 반복할 수 있습니다. 아래의 '패치 재정의'를 참고하세요 |
+| `--no-template` | 템플릿을 복제하지 않고 머신을 단독으로 복원 |
+| `--slim on\|off`, `--trim …`, `--keep-languages …`, `--service-profile …`, `--remove-apps …`, `--keep-apps …` | `vphone-cli vm create`의 경량화 스위치. New Machine과 마찬가지로 Apple 계정은 trimmed 서비스 프로필과 함께 꺼집니다 |
+| `--accounts-off` | 받기는 하지만 아무것도 바꾸지 않습니다 |
+| `--ipsw <path>` | 선택 사항. New Machine의 ipsw 필드처럼, 이 경로로 kernelcache 믹스를 준비하는 2.12.0 번들에만 전달됩니다. 2.12.1 번들은 네이티브로 추출합니다 |
+| `--kmutil-ssh <user@host>` | New Machine의 macOS 빌더 필드처럼, iOS 18 게스트(`--device iPhone11,6`)의 kernel-first 믹스를 ssh로 링크하는 Mac. 그곳의 ssh와 sudo 암호는 인자가 아니라 항상 클라이언트의 `VPHONE_KMUTIL_SSH_PASSWORD`에서 가져옵니다 |
+| `--from <step>` | 생성을 시작할 때의 옵션으로 특정 단계(`findTemplate` … `firstBoot`)부터 다시 시도 |
+
+파서는 `--iphone-source`, `--cloudos-source`, `--cpu`, `--memory`, `--disk-size`, `--network`, `--keep-artifacts`, `--no-wait`도 받습니다. `vphone-launchpad-cli help`를 참고하세요.
+
+결과에는 템플릿, 이번 생성에서 템플릿을 빌드했는지 여부, 사용한 패치가 표시됩니다.
+
+### 다른 기기
+
+| `--device` | 게스트 | 참고 |
+| --- | --- | --- |
+| iPad 제품 유형 | iPadOS | [iPadOS 게스트](../firmware/ipados.md)를 참고하세요 |
+| `AppleTV5,3` | Apple TV HD | 항상 경량화 없이 단독으로 복원됩니다. `--preset`으로 다른 프리셋을 지정하지 않으면 `tvos` 프리셋을 사용합니다 |
+| `AppleTV14,1` | Apple TV 4K(3세대) | 위와 같으며, `tvos-4k` 프리셋과 카탈로그 OTA의 사용자 영역을 사용합니다 |
+| `AppleTV18,1` | Apple TV 4K(4세대) | Launchpad와 Core Bundle 2.13이 필요합니다. `tvos-4k`를 선택하고, 경량화 없이 단독으로 복원하며, Apple TV HD 기반 위에 전체 OTA로 tvOS 27.2 베타(`24K120`)를 사용합니다. 생성에는 macOS 27이 필요합니다. 실제 부팅은 아직 확인되지 않았습니다. [초기 구동 기록](../../../Research/Firmware/tvos_support.md#apple-tv-4k-4th-generation)을 참고하세요 |
+
+다음 두 경우에는 도우미를 통해 일부 단계를 root로 실행합니다.
+
+- `--preset minimal`(Minimal: 순정 부트 체인, 커널, TXM을 사용하고 복원 전에 시스템을 사용자화)도 경량화 없이 단독으로 복원되며, `fw patch`는 도우미를 통해 root로 실행됩니다. Userspace debugging 상자(`vphone-cli fw patches`의 Features 아래 `userspace-debugging`)는 그 상자가 나열하는 각 패치에 대한 `--allow`에 해당합니다.
+- cloudOS에 vphone600 구성 요소가 없는 머신(해당 릴리스 자체의 cloudOS, Watch, iOS 18 게스트)은 `fw kernelcache`로 kernelcache 믹스를 준비하고 도우미가 root로 링크합니다.
+
+### 패치 재정의
+
+`--block <patch>`와 `--allow <patch>`는 `vphone-cli fw patches`가 나열하는 식별자를 패치마다 하나씩 받습니다.
+
+```sh
+vphone-launchpad-cli exec fw patches --preset <preset>
+```
+
+Launchpad는 생성 작업의 번들에서 그 카탈로그를 읽고, 어느 패치 세트에도 선언되지 않은 식별자나 차단과 허용이 동시에 지정된 식별자를 거부하며, `fw set-patches`처럼 프리셋과 다른 것만 보관합니다. 그런 다음 New Machine과 같은 방식으로 나눕니다.
+
+- **부트 체인 패치**(AVPBooter, iBSS, iBEC, LLB, TXM, kernelcache, DeviceTree …)는 템플릿 키에 포함됩니다. Find Template은 그 패치로 빌드된 템플릿을 찾고, 템플릿 빌드는 `fw patch` 전에 `fw set-patches`로 이를 기록합니다.
+- **게스트 패치**는 템플릿에 포함되지 않습니다. 복제본이 `fw set-patches`로 이를 기록하고, Apply Guest Patches 단계가 첫 부팅 전에 도우미를 통해 `cfw update-environment`로 적용합니다. 따라서 게스트 재정의만 있으면 일반 템플릿을 재사용합니다.
+
+결과의 `patches` 객체에는 프리셋, `blocked`와 `allowed` 재정의, 그리고 복제본에 적용된 `guest` 재정의가 들어 있습니다. `--no-template`이면 모든 재정의가 머신 자체의 복원에 들어갑니다. `--from`은 `--block`과 `--allow`를 거부합니다. 재시도는 생성 작업의 패치를 그대로 유지합니다.
+
+## 결과의 번들 필드
+
+| 명령 | 필드 | 의미 |
+| --- | --- | --- |
+| `status` | `defaultBundle` | 기본 버전. 이전 스크립트를 위해 `activeBundle`에도 같은 값이 들어 있습니다 |
+| `bundle list` | `default` | 이 버전이 기본 버전임. 이전 스크립트를 위해 `active`에도 같은 값이 들어 있습니다 |
+| `bundle list` | `machines` | 이 버전에 연결된 머신의 이름 |
+| `vm list` | `bundle` | 머신의 호스트 프로그램이 실행되는 버전 |
+| `vm list` | `guestEnvironmentBundle` | 게스트 환경이 마지막으로 설치된 버전. 알 수 없으면 `null` |
+| `vm list` | `bootChainBundle` | 부트 체인을 빌드한 버전. Launchpad가 이를 기록하기 전에 만든 머신은 `null` |
+| `vm create`, `cfw …`, `exec` | `bundle` | 명령이 실행된 버전 |
+
+`guestEnvironmentBundle`이 `bundle`과 다르면 호스트와 게스트가 서로 다른 빌드에서 온 것입니다. `cfw update-environment`로 게스트를 맞추세요.
+
+## 터치 좌표와 디스플레이 형상
+
+`guest send`의 터치 좌표는 `t:screenshot`이 반환하는 **똑바로 세운 전체 스크린샷**을 기준으로 합니다. 4분의 1 회전하면 너비와 높이가 바뀝니다. 호스트는 GUI와 헤드리스 시작 모두에서 그 지점을 고정 패널 HID 좌표로 변환합니다. 스와이프는 시작 시점에 측정한 형상을 유지합니다. 스크린샷 도중 형상이 바뀌면, 입력 좌표가 모호한 이미지 대신 오류가 반환됩니다.
+
+회전된 좌표의 불일치를 진단하려면 형상을 읽으세요.
+
+```sh
+vphone-launchpad-cli guest send <name> '{"t":"display.geometry"}'
+```
+
+호스트에 구성된 픽셀 크기와 캡처된 픽셀 크기, 그리고 실시간 디스플레이 뷰의 경계, 회전, 화면비를 유지한 그리기 영역, 포인터/터치 경로를 반환하며, 입력이나 디스플레이 상태는 바꾸지 않습니다. `capture_pixels`는 호스트의 원시 프레임이고, `screenshot_pixels`와 `input_orientation`은 입력 좌표를 나타냅니다. 이를 `device.screen`, `display.orientation`, 그리고 게스트가 실제로 받는 이벤트와 비교하세요.
+
+## 연결 방식
+
+CLI는 `~/Library/Application Support/vphone-launchpad/control.sock`의 Unix 소켓(모드 0600, 같은 사용자에게만 제공)으로 실행 중인 Launchpad와 통신합니다. CLI에는 권한도 자체 상태도 없습니다. 번들은 Launchpad의 도우미를 통해 설치되며, 각 머신은 자신의 Core Bundle에 있는 `vphone-cli`로 실행됩니다. 네트워크에서 수신하는 것은 없습니다. 다른 컴퓨터에서 사용하려면 ssh로 접속하세요.
+
+## 함께 보기
+
+- [코어 번들과 로컬 빌드](core-bundles.md)
+- [번들 통합](bundle-integration.md)
+- [생성 및 실행](../machines/create-and-run.md)
diff --git a/Documents/ko/machines/automation-api.md b/Documents/ko/machines/automation-api.md
new file mode 100644
index 00000000..78852e33
--- /dev/null
+++ b/Documents/ko/machines/automation-api.md
@@ -0,0 +1,78 @@
+# 자동화 API
+
+실행 중인 가상 머신을 스크립트에서 HTTP와 WebSocket으로 제어합니다. 이 페이지에서는 API를 켜고, 인증하고, 첫 호출을 보내는 방법을 설명합니다. 모든 경로와 메서드는 [전체 API 레퍼런스](../../../Research/vphoned_http_api.md)에 있습니다.
+
+## 켜기
+
+가상 머신을 시작할 때 `--api-listen`을 추가합니다.
+
+```sh
+vphone-cli vm launch myphone --api-listen 127.0.0.1:8765
+```
+
+가상 머신이 시작되면 `vphone-vm`이 주소와 token을 출력합니다.
+
+```text
+[api] HTTP/WebSocket API: http://127.0.0.1:8765
+[api] token: 3f9c…
+[api] send it as: Authorization: Bearer 3f9c…
+```
+
+- `--api-listen`이 없으면 호스트에서 수신하는 리스너가 없습니다.
+- 포트를 `0`으로 지정하면 macOS가 비어 있는 포트를 할당하며, 실제 주소는 가상 머신이 시작된 뒤 출력됩니다.
+- `--api-listen`은 `--dfu`와 함께 사용할 수 없습니다.
+
+> [!WARNING]
+> vphoned는 root로 실행되며, API로 게스트의 모든 파일을 읽고 쓰고, 키체인을 나열하고, launch daemon을 로드할 수 있습니다. 로컬에서만 사용하려면 `127.0.0.1` 또는 `[::1]`에서 수신하세요. 그 밖의 주소를 지정하면 경고가 출력됩니다. 그 주소에 접근할 수 있는 모든 컴퓨터는 token만 있으면 되고, token은 일반 HTTP로 평문 전송되므로 신뢰할 수 있는 네트워크에서만 사용하세요.
+
+## token
+
+token은 시작할 때마다 새로 만들어지며, 32바이트 난수를 16진수로 표현한 값입니다. 고정된 token을 사용하려면 시작하기 전에 `VPHONE_API_TOKEN`을 설정하세요. `vphone-cli vm launch`는 자신의 환경 변수를 `vphone-vm`에 그대로 넘깁니다. 값은 `A-Z a-z 0-9 - . _ ~`로 이루어진 16~256자여야 하며, 비어 있지 않은 다른 값이면 시작이 중단됩니다.
+
+token은 다음 중 어느 형식으로든 보낼 수 있습니다.
+
+| 형식 | 용도 |
+| --- | --- |
+| `Authorization: Bearer <token>` 헤더 | HTTP, 그리고 헤더를 설정할 수 있는 WebSocket 클라이언트 |
+| `token=<token>` 쿼리 항목 | `ws://127.0.0.1:8765/v1/events?token=<token>` 같은 WebSocket URL |
+| `Sec-WebSocket-Protocol: vphone-token.<token>` | 서브프로토콜만 설정할 수 있는 WebSocket 클라이언트 |
+
+token이 없거나 틀리면 `401 Unauthorized`가 반환되고, 게스트에 아무것도 전달되기 전에 연결이 닫힙니다.
+
+## 호출 예시
+
+```sh
+TOKEN=... # from the "[api] token:" line, or the VPHONE_API_TOKEN you set
+
+# Health check
+curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8765/v1/health
+
+# Call any method through /v1/rpc
+curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+ -d '{"method":"device.snapshot","params":{}}' http://127.0.0.1:8765/v1/rpc
+
+# Event stream
+websocat "ws://127.0.0.1:8765/v1/events?token=$TOKEN"
+
+# Interactive shell in the guest (websocat needs --binary)
+websocat --binary "ws://127.0.0.1:8765/v1/shell?token=$TOKEN&cols=120&rows=40"
+```
+
+클라이언트를 직접 작성할 때 걸리기 쉬운 규칙은 다음과 같습니다.
+
+- 모든 `POST`는 `Content-Type: application/json`을 보내야 하며, 그렇지 않으면 `415`가 반환됩니다.
+- `Origin` 헤더가 있는 요청, 또는 `Host`가 `vphoned`, `localhost`, `127.0.0.1`, `::1`이 아닌 요청에는 `403`이 반환됩니다. 이렇게 웹 페이지가 API에 접근하지 못하도록 막습니다.
+- `GET` 경로는 읽기만 합니다. 설정을 변경하려면 `PUT`이나 `POST`를 사용하세요. 예를 들어 `PUT /v1/low-power-mode`에 `{"enabled": true}`를 보냅니다.
+
+Swift 앱에서는 `VPhoneAPIKit` 패키지의 `VPhoneAPIClient`를 사용할 수 있으며, token은 이 클라이언트가 알아서 보냅니다. 예시는 레퍼런스를 참고하세요.
+
+## 네트워크 리스너 없이 사용하기
+
+가상 머신의 제어 소켓은 API 리스너 없이도 같은 메서드를 받습니다. `{"t":"rpc","method":"<method>","params":{}}`를 JSON 한 줄로 보내세요. [가상 머신 생성 및 실행](create-and-run.md)의 '제어 소켓' 절을 참고하세요.
+
+## 함께 보기
+
+- [전체 API 레퍼런스](../../../Research/vphoned_http_api.md)
+- [가상 머신 생성 및 실행](create-and-run.md)
+- [포트 포워딩](../networking/port-forwarding.md)
+- [Launchpad 명령줄](../launchpad/launchpad-cli.md)
diff --git a/Documents/ko/machines/boot-roms.md b/Documents/ko/machines/boot-roms.md
new file mode 100644
index 00000000..3a8d3a39
--- /dev/null
+++ b/Documents/ko/machines/boot-roms.md
@@ -0,0 +1,51 @@
+# 부트 ROM
+
+가상 머신이 시작할 때 사용할 부트 ROM과 SEP 부트 ROM을 선택합니다. 이 페이지에서는 가상 머신이 사용하는 ROM을 확인하거나 오픈 소스 ROM과 Apple의 ROM 사이에서 전환하는 방법을 설명합니다.
+
+## 확인 및 전환
+
+```sh
+vphone-cli vm info myphone # shows rom and seprom
+vphone-cli vm config myphone --rom openavb --seprom opensep # open-source ROMs
+vphone-cli vm config myphone --rom apple --seprom apple # Apple's ROMs
+```
+
+전환은 복원 없이 가상 머신의 다음 시작부터 적용되며, 어느 방향으로든 가능합니다.
+
+| 옵션 | 값 | ROM |
+| --- | --- | --- |
+| `--rom` | `openavb` | 번들에 포함된 OpenAVB |
+| `--rom` | `apple` | Virtualization.framework의 AVPBooter(머신에 패치된 사본이 있으면 그 사본) |
+| `--rom` | 파일 경로 | 그 밖의 부트 ROM |
+| `--seprom` | `opensep` | 번들에 포함된 OpenSEP |
+| `--seprom` | `apple` | Virtualization.framework의 AVPSEPBooter |
+| `--seprom` | 파일 경로 | 그 밖의 SEP 부트 ROM |
+
+두 부트 ROM은 같은 패치된 LLB를 로드하고, 두 SEP ROM은 복원 때 설치된 SEP 펌웨어를 로드합니다. 그래서 복원이 필요하지 않습니다.
+
+> [!NOTE]
+> OpenAVB로 부팅하는 가상 머신을 복원하려면 `VPhone.bundle` 2.10.1 이상이 필요합니다.
+
+## 가상 머신이 사용하는 ROM
+
+새 가상 머신은 Virtualization.framework에 포함된 비공개 ROM 대신 두 가지 오픈 소스 ROM으로 시작합니다.
+
+- [OpenAVB](https://github.com/owngoal-dev/OpenAVB)는 부트 ROM인 AVPBooter를 대신합니다. 패치가 필요 없으므로 `fw patch`가 건드리지 않습니다.
+- [OpenSEP](https://github.com/owngoal-dev/OpenSEP)는 SEP 부트 ROM인 AVPSEPBooter를 대신합니다.
+
+둘을 함께 쓰면 iBoot와 SEPOS 이전에 실행되는 코드 중 Apple이 작성한 것은 없습니다. 이전 버전에서 만든 가상 머신은 전환하기 전까지 Apple의 ROM을 계속 사용합니다.
+
+## ROM의 출처
+
+두 ROM 모두 고정된 업스트림 커밋에서 미리 빌드되어 `VPhone.bundle`에 포함됩니다. 각 README에 다시 빌드하고 바이트 단위로 대조하는 방법이 있습니다.
+
+- [OpenAVB README](../../../VPhoneExecutable/VPhoneVirtualization/Resources/OpenAVB/README.md)
+- [OpenSEP README](../../../VPhoneExecutable/VPhoneVirtualization/Resources/OpenSEP/README.md)
+
+자세한 내용은 [OpenAVB](../../../Research/Firmware/openavb_boot_rom.md)와 [OpenSEP](../../../Research/Firmware/opensep_sep_rom.md)에 관한 연구 기록을 참고하세요.
+
+## 함께 보기
+
+- [가상 머신 생성 및 실행](create-and-run.md)
+- [펌웨어 준비](../firmware/firmware-preparation.md)
+- [문제 해결](../help/troubleshooting.md)
diff --git a/Documents/ko/machines/create-and-run.md b/Documents/ko/machines/create-and-run.md
new file mode 100644
index 00000000..6db614d6
--- /dev/null
+++ b/Documents/ko/machines/create-and-run.md
@@ -0,0 +1,121 @@
+# 가상 머신 생성 및 실행
+
+터미널에서 `vphone-cli`로 가상 머신을 만들고, 시작하고, 중지합니다. Launchpad 없이 작업하거나, 가상 머신 생성을 스크립트로 처리하거나, 과정의 한 단계를 다시 실행해야 할 때 이 페이지를 사용하세요.
+
+Launchpad는 `VPhone.bundle` 안의 `vphone-cli`로 가상 머신을 제어하며, 같은 명령을 터미널에서도 사용할 수 있습니다.
+
+```sh
+vphone-cli vm list
+vphone-cli vm launch myphone
+vphone-cli vm export myphone --out myphone.tzst
+```
+
+가상 머신은 `~/.vphone/`에 저장됩니다. 전체 명령은 `vphone-cli <group> --help`로 확인하세요.
+
+## 가상 머신 만들기
+
+iPhone17,3 복원 IPSW와 호환되는 PCC/cloudOS IPSW가 로컬 경로나 URL로 필요합니다. 지금까지 검증된 조합은 [호환성](../firmware/compatibility.md)에 있습니다.
+
+```sh
+vphone-cli host preflight
+vphone-cli vm create myphone \
+ --iphone-source /path/to/iPhone17,3_Restore.ipsw \
+ --cloudos-source /path/to/cloudOS.ipsw
+```
+
+생성은 준비, 펌웨어 패치, 온라인 DFU 복원, 호스트에서 마운트한 CFW 설치, 첫 GUI 부팅 순서로 진행됩니다.
+
+- 복원 티켓을 받기 위해 네트워크 연결이 필요합니다.
+- CFW 설치에는 root 권한이 필요합니다. 번들에는 인증 대화상자나 권한 도우미가 없으므로 root 권한은 사용자가 직접 제공해야 합니다.
+- 기본 가상 디스크 크기는 64 GB입니다.
+
+성공하면 `[+] First boot: vphoned ping succeeded.`와 `CFW VM created; vphoned connected. Guest user environment is untouched.`가 출력되며 끝납니다. 그런 다음 가상 머신은 중지됩니다. ping은 그 부팅 중에 vphoned가 응답했다는 것을 확인하며, 실행 중인 가상 머신은 남지 않습니다.
+
+### 옵션
+
+| 옵션 | 효과 |
+| --- | --- |
+| `--iphone-version`, `--iphone-build` | `--iphone-source`를 넘기는 대신 `fw prepare`처럼 `--device`(기본값 iPhone17,3)에 맞는 iPhone IPSW를 찾습니다. |
+| `--cloudos-source` 생략 | `fw catalog`에 표시되는 대로, 카탈로그가 해당 릴리스에 권장하는 cloudOS를 사용합니다. |
+| `--disk-size` | 가상 디스크 크기(GB, 기본값 64). |
+| `--preset` | 패치 프리셋 이름 또는 프리셋 plist 경로(기본값 `standard`). 각 프리셋이 적용하는 패치는 `fw patches`로 확인하세요. |
+| `--cpu` | CPU 코어 수(기본값 8). |
+| `--memory` | 메모리(MB, 기본값 8192). |
+| `--network` | `nat`(기본값), `bridged`, `tunnel`, `none`. |
+| `--unlock-at-startup` | `on` 또는 `off`(기본값). |
+| `--no-template` | 템플릿에서 복제하지 않고 가상 머신을 단독으로 만듭니다. |
+| `--skip-first-boot` | 마지막 부팅을 생략합니다. 호출하는 쪽에서 가상 머신을 직접 부팅할 때 사용합니다. |
+| `--bootstrap roothide` | 첫 부팅 중에 패키지 환경을 설치합니다. [패키지 환경](package-environment.md)을 참고하세요. |
+| `--keep-artifacts` | 준비 과정에서 만든 큰 복원 트리를 보존합니다. 디스크 공간이 중요하면 생략하세요. |
+
+`--cpu`, `--memory`, `--network`, `--unlock-at-startup`은 새 가상 머신에 같은 이름의 `vm config` 설정을 지정합니다.
+
+### 템플릿
+
+기본적으로 파이프라인은 [템플릿](../storage/templates.md)을 만들고 그 템플릿에서 가상 머신을 복제합니다. 이후 기기, iOS 및 cloudOS 빌드, 프리셋, 디스크 크기가 같은 `vm create`는 다시 복원하지 않고 그 템플릿에서 복제합니다. 가상 머신을 단독으로 만들려면 `--no-template`을 넘기세요.
+
+### 패치와 펌웨어 준비
+
+펌웨어 작업 흐름에는 모드가 하나뿐입니다. 부트 체인과 게스트 시스템을 패치하고 vphoned를 설치하며, 사용자 환경은 비워 둡니다. Sileo, apt, TrollStore, SSH 서버, VNC 서버는 설치하지 않습니다. 적용할 패치는 패치 프리셋이 선택하며, `vphone-cli fw set-patches`에 `--block` 또는 `--allow`를 지정하면 개별 패치를 끄거나 켤 수 있습니다.
+
+패치하기 전에 생성 과정에서 펌웨어를 준비합니다. 임시 cloudOS 복원으로 GPU 드라이버를 얻고, vphone600 구성 요소가 없는 cloudOS에는 다시 빌드한 kernelcache가 필요합니다. [펌웨어 준비](../firmware/firmware-preparation.md)를 참고하세요. 목록 하나로 여러 머신을 만들려면 [여러 머신 만들기](../storage/many-machines.md)를 참고하세요.
+
+## 시작 및 중지
+
+```sh
+vphone-cli vm launch myphone # start the VM window and keep it running
+vphone-cli vm stop myphone # run from another terminal to stop it
+```
+
+`vm launch`는 vphoned를 기다리지 않고 게스트를 시작하며, 데몬은 부팅 중에 연결됩니다. 가상 머신 창과 메뉴에서 홈 버튼과 전원 버튼, 앱 설치, 파일 탐색을 사용할 수 있습니다. `vm launch --headless`는 가상 머신 창과 메뉴 막대 없이 부팅합니다.
+
+다음은 모두 게스트를 정상적으로 종료합니다(vphoned `system.shutdown`).
+
+- 가상 머신 창 닫기
+- ⌘Q
+- `vm stop`
+- `vm launch`를 실행한 터미널에서 Control-C
+
+가상 머신은 게스트가 멈추면 종료되며, 15초가 지나도 멈추지 않으면 그때 종료됩니다. DFU 상태이거나 아직 시작 중인 게스트처럼 vphoned가 응답할 수 없는 게스트는 전원을 뽑은 것처럼 즉시 꺼집니다. Control-C를 한 번 더 누르면 기다리지 않고 끕니다.
+
+`vm stop`은 머신 자신의 프로세스인 `vphone-vm`과 Virtualization의 가상 머신 서비스에만 신호를 보냅니다. 크기를 측정하는 Launchpad, Spotlight, 백업 도구처럼 디스크를 열고 있는 다른 프로그램은 이름만 표시하고 그대로 둡니다.
+
+## 제어 소켓
+
+실행 중인 각 가상 머신은 자신의 폴더에 제어 소켓 `vphone.sock`(`~/.vphone/machines/<name>/vphone.sock`)을 둡니다. JSON 한 줄을 보내면 JSON 한 줄이 돌아옵니다. 연결은 동시에 처리되며, 창이 없는 가상 머신에도 소켓이 있습니다. 이 경우 `tap`과 `swipe`는 vphoned의 터치 주입으로 처리되고 화면 이미지는 게스트에서 가져옵니다.
+
+`tap`, `swipe`, `key`, `screenshot` 외에도 `rpc` 요청으로 [API 레퍼런스](../../../Research/vphoned_http_api.md)에 있는 모든 vphoned 메서드를 호출할 수 있습니다.
+
+```sh
+printf '%s\n' '{"t":"rpc","method":"device.info","params":{}}' | nc -U ~/.vphone/machines/myphone/vphone.sock
+```
+
+예를 들어 `input.key`에 `{"name":"cmd+v"}`를 보내면 붙여 넣고, `input.type`은 텍스트를 입력합니다. 이 작업 흐름은 SSH나 VNC 엔드포인트를 설치하지 않습니다. HTTP와 WebSocket으로 접근하려면 [자동화 API](automation-api.md)를 참고하세요.
+
+## 각 단계를 직접 실행하기
+
+한 단계를 조사하거나 다시 실행할 때 사용합니다. `restore`가 통신하는 동안 DFU 부팅을 계속 실행해 두세요.
+
+```sh
+vphone-cli vm new myphone
+vphone-cli fw prepare myphone \
+ --iphone-source /path/to/iPhone17,3_Restore.ipsw \
+ --cloudos-source /path/to/cloudOS.ipsw
+vphone-cli fw patch myphone
+
+vphone-cli vm launch myphone --dfu &
+vphone-cli restore myphone
+vphone-cli vm stop myphone
+
+vphone-cli cfw install myphone
+vphone-cli vm launch myphone
+```
+
+온라인 복원은 프로세스 안에서 티켓을 받습니다. 오프라인 복원은 `vphone-cli restore --help`에서 `--get-shsh`와 `--offline`을 확인하세요. 수동 흐름에서는 `vm create`가 수행하는 첫 부팅 ping 확인을 실행하지 않습니다.
+
+## 함께 보기
+
+- [템플릿](../storage/templates.md)
+- [기기 이름과 시계](device-name-and-clock.md)
+- [보관함과 백업](../storage/library-and-backups.md)
+- [디스크 공간 공유](../storage/sharing-disk-space.md)
diff --git a/Documents/ko/machines/device-name-and-clock.md b/Documents/ko/machines/device-name-and-clock.md
new file mode 100644
index 00000000..78e39c1c
--- /dev/null
+++ b/Documents/ko/machines/device-name-and-clock.md
@@ -0,0 +1,42 @@
+# 기기 이름과 시계
+
+게스트는 기기 이름을 가상 머신에서, 시계와 시간대를 Mac에서 가져옵니다. 게스트의 이름이나 시간이 예상과 다를 때 이 페이지를 읽으세요.
+
+## 기기 이름
+
+게스트에 표시되는 이름을 바꾸려면 가상 머신의 이름을 바꿉니다.
+
+```sh
+vphone-cli vm rename myphone <new-name>
+```
+
+게스트는 가상 머신의 이름을 기기 이름으로 표시하며, Xcode의 기기 목록과 `xcrun devicectl list devices`에도 이 이름이 나타납니다.
+
+- 게스트 안에서, 또는 Finder, Xcode, `idevicename`에서는 기기 이름을 바꿀 수 없습니다. 그곳에서 이름을 바꾸면 성공했다고 표시되지만 아무것도 바뀌지 않습니다.
+- `vm rename` 후 머신이 켜지면 Finder와 `ideviceinfo`에는 곧바로 새 이름이 표시됩니다. Xcode와 `devicectl`은 기기가 나타날 때 이름을 읽으므로 다음 부팅까지 이전 이름을 표시할 수 있습니다.
+- 가상 머신 이름이 UTF-8로 255바이트를 넘거나 제어 문자를 포함하면 사용되지 않으며, 게스트는 자신의 이름을 표시합니다.
+
+`vphone-vm`은 부팅할 때마다 몇 초 뒤 vphoned에 연결하면서 이름을 게스트에 전달하며, 게스트는 다음 부팅까지 이 이름을 유지합니다. 게스트 자신의 이름은 환경설정에 그대로 남아 있습니다.
+
+이 기능이 있는 번들로 옮긴 기존 머신은 환경 업데이트와 함께 게스트 라이브러리를 받고, 그다음 부팅부터 이를 사용합니다.
+
+구현은 [`Research/Guest/device_name_pinning.md`](../../../Research/Guest/device_name_pinning.md)를 참고하세요.
+
+## 시계와 시간대
+
+게스트는 Mac의 시간대와 시계를 따릅니다. 따로 설정할 것은 없습니다.
+
+`vphone-vm`은 vphoned에 연결할 때마다 Mac의 시간대를 보내고, 그때와 그 뒤 1분마다 Mac의 시간을 보냅니다. 하루 동안 꺼져 있었거나 잠자기 중인 Mac에서 멈춰 있던 게스트도 NTP 서버에 접속하지 않고 1분 안에 Mac의 시간으로 돌아옵니다. Mac과의 차이가 1초 이내인 게스트는 건드리지 않습니다.
+
+게스트에 다른 날짜나 시간을 지정하려면 다음과 같이 합니다.
+
+1. 게스트에서 **설정 > 일반 > 날짜 및 시간**을 엽니다.
+2. 날짜나 시간을 선택합니다. 이렇게 하면 게스트의 자동 시간 설정이 꺼지고, Mac의 시간이 더 이상 적용되지 않습니다.
+
+Mac의 시간으로 돌아가려면 같은 곳에서 **자동으로 설정**을 다시 켭니다.
+
+## 함께 보기
+
+- [가상 머신 생성 및 실행](create-and-run.md)
+- [보관함과 백업](../storage/library-and-backups.md)
+- [네트워크](../networking/overview.md)
diff --git a/Documents/ko/machines/package-environment.md b/Documents/ko/machines/package-environment.md
new file mode 100644
index 00000000..f94ce97e
--- /dev/null
+++ b/Documents/ko/machines/package-environment.md
@@ -0,0 +1,50 @@
+# 패키지 환경
+
+가상 머신에 패키지 관리자를 설치하거나 제거합니다. 새 가상 머신에는 패키지 관리자가 없습니다. 게스트에서 `apt`, 셸, SSH 등 명령줄 도구가 필요할 때 이 페이지를 따르세요.
+
+## 설치
+
+1. 가상 머신 창의 메뉴 막대에서 **Apps > Install Bootstrap…**을 선택하고 **roothide** 레이아웃을 선택합니다(**rootless**는 더 이상 권장되지 않습니다). 가상 머신에 Irisin이 설치됩니다.
+2. Irisin에서 **OwnGoal Packages** 저장소를 열고 **OwnGoal Bootstrap for vphone**(`owngoal-bootstrap-vphone`)을 찾아 **Bootstrap Install**로 설치합니다.
+3. 처음 설치를 마친 뒤에는 다른 패키지를 일반적인 방법으로 설치합니다.
+
+`owngoal-bootstrap-vphone` 하나로 가상 머신에 필요한 것이 한 번에 설치됩니다. `apt`와 `dpkg`, `bash`, `zsh`와 `dash`, `sudo`, 기본 명령줄 도구, `openssh-server`, `curl`, `wget`, `vim`, `git`, `uikittools`, `launchctl`, 그리고 OwnGoal 앱입니다.
+
+> [!WARNING]
+> 이 패키지들을 하나씩 설치하지 마세요. 일부 패키지는 서로 의존하며, `openssh-server`는 일부 의존성을 순환하도록 선언하고 있어 따로 설치하면 도중에 실패할 수 있습니다.
+
+처음 설치에 실패하면 그 자리에서 복구하려 하지 마세요. **Apps > Uninstall Bootstrap…**을 선택한 뒤 1단계부터 다시 시작합니다.
+
+### 가상 머신을 만들면서 설치하기
+
+```sh
+vphone-cli vm create myphone --bootstrap roothide ...
+```
+
+`--bootstrap roothide`는 새 머신의 첫 부팅 중에 1단계와 2단계를 수행합니다. Irisin을 설치한 뒤, Irisin이 권장하는 저장소에서 `irisin-cli`를 통해 `owngoal-bootstrap-vphone`을 Bootstrap Install로 설치합니다. 2단계에는 `irisin-cli install`이 `--repository`와 `--bootstrap-install`을 지원하는 Irisin이 필요합니다.
+
+## 제거
+
+**Apps > Uninstall Bootstrap…**을 선택합니다. 제거 후 가상 머신이 재시동됩니다.
+
+Irisin은 데이터(다운로드, 기록, 설정)를 홈 아래의 `Documents/wiki.qaq.irisin`에 보관합니다.
+
+| 레이아웃 | Irisin의 홈 | 제거 후 |
+| --- | --- | --- |
+| roothide | 환경 자체의 `/var/mobile` | 데이터가 다른 모든 것과 함께 제거됩니다. |
+| rootless | 시스템의 `/var/mobile` | 데이터가 남습니다. |
+
+## 추가 옵션
+
+Option 키를 누른 채 **Apps** 메뉴를 열면 두 가지 항목이 더 나타납니다.
+
+- **Install Bootstrap from File…:** 로컬 Irisin `.deb`로 설치합니다.
+- **Uninstall Bootstrap Without Restarting…:** 가상 머신을 재시동하지 않고 환경을 제거합니다.
+
+같은 작업을 자동화 API(`bootstrap.install`, `bootstrap.status`)로도 할 수 있습니다. [API 레퍼런스](../../../Research/vphoned_http_api.md)를 참고하세요.
+
+## 함께 보기
+
+- [가상 머신 생성 및 실행](create-and-run.md)
+- [자동화 API](automation-api.md)
+- [문제 해결](../help/troubleshooting.md)
diff --git a/Documents/ko/networking/addresses.md b/Documents/ko/networking/addresses.md
new file mode 100644
index 00000000..ccfa3f3c
--- /dev/null
+++ b/Documents/ko/networking/addresses.md
@@ -0,0 +1,80 @@
+# MAC 및 IP 주소
+
+이 페이지에서는 게스트에 저장된 MAC 주소, 이전 MAC이 아직 차지하고 있는 DHCP 임대의 해제, 게스트에 고정 IPv4 주소를 지정하는 방법을 다룹니다.
+
+## MAC 주소
+
+처음 시작할 때 게스트의 네트워크 카드에 무작위로 생성한 로컬 관리 MAC 주소를 부여하고, 머신 식별자와 마찬가지로 `config.plist`에 저장합니다. 그러면 게스트는 시작할 때마다 같은 식별 정보와 같은 DHCP 임대를 유지합니다.
+
+설정하거나 교체하려면 다음을 실행합니다.
+
+```sh
+vphone-cli vm config <name> --mac 02:11:22:33:44:55
+vphone-cli vm config <name> --mac random # a new one now
+vphone-cli vm config <name> --mac auto # a new one at the next launch
+```
+
+복제한 머신은 머신 식별자처럼 원본의 MAC을 유지합니다. 둘을 동시에 실행하려면 사본에 새 식별 정보와 MAC을 부여하는 `vm clone --new-identity`로 복제하거나, 사본에 새 MAC을 지정하세요. `--new-identity`는 사본의 고정 주소, 포트 포워딩, mDNS 이름도 지웁니다.
+
+## 이전 MAC이 차지하고 있는 주소
+
+증상: `nat` 모드에서 새 게스트가 점점 더 높은 주소를 받다가, 결국 범위의 높은 쪽에 지정해 둔 고정 주소에까지 이릅니다.
+
+공유 네트워크의 임대와 각 임대의 소유자를 나열한 뒤, 고아 임대를 해제합니다(`VPhone.bundle` 2.5 이상 필요).
+
+```sh
+vphone-cli vm leases
+sudo vphone-cli vm leases --release-orphans
+```
+
+Launchpad를 통해서는 다음과 같습니다.
+
+```sh
+vphone-launchpad-cli vm leases
+vphone-launchpad-cli vm leases --release
+```
+
+Launchpad 창에서는 Host Setup의 NAT Network 아래에 개수가 표시되며, Release…를 누르고 관리자가 승인하면 해제됩니다. Launchpad는 자신이 나열하는 모든 보관함을 기준으로 비교합니다.
+
+고아 임대란 MAC이 보관함의 어느 머신에도 속하지 않고 임대 기간이 끝난 iOS 또는 iPadOS 게스트의 임대입니다. `--release-orphans`는 `/var/db/dhcpd_leases`에서 고아 임대를 제거하고 DHCP 서버가 파일을 다시 읽게 하므로 root 권한이 필요합니다. 다음은 절대 건드리지 않습니다.
+
+- 머신 자신의 임대. 머신이 중지된 동안 기간이 끝난 임대도 포함합니다.
+- 기간이 끝나지 않은 임대. 예를 들어 MAC을 방금 교체한 실행 중인 게스트의 임대입니다.
+- 다른 가상 머신 앱의 임대, 또는 인터넷 공유에 연결된 기기의 임대.
+
+다른 보관함의 머신은 그 보관함도 지정했을 때만 계산됩니다. 보관함마다 `--library-root`를 반복하세요. 보관함에 머신이 없거나 머신의 설정을 읽을 수 없으면, 그곳의 모든 임대가 고아로 보이게 되므로 해제를 거부합니다.
+
+원인: Mac의 DHCP 서버는 임대 기간이 끝난 뒤에도 각 주소를 그 주소를 받은 MAC에 묶어 두며, 범위의 다른 모든 주소가 사용된 뒤에야 그 주소를 다른 기기에 넘깁니다. 머신을 삭제하거나 MAC을 교체하면 그 주소는 더 이상 아무도 쓰지 않는 MAC에 묶인 채 남으며, MAC이 저장되기 전에 이루어진 모든 시작도 마찬가지입니다.
+
+## 고정 주소
+
+`--ip`는 게스트에 고정 IPv4 주소를 지정합니다. 접두사 길이를 생략하면 `/24`로 간주합니다. `--gateway`와 `--dns`는 선택 사항이며, `auto`를 지정하면 기본값으로 돌아갑니다. `--ip dhcp`는 고정 주소를 제거합니다.
+
+```sh
+vphone-cli vm config <name> --ip 192.168.65.50
+vphone-cli vm config <name> --network tunnel --ip 10.20.0.5/16 --dns 1.1.1.1
+vphone-cli vm config <name> --ip dhcp
+```
+
+주소가 게스트에 적용되는 방식은 모드에 따라 다릅니다.
+
+| 모드 | 주소 | 적용 방식 |
+| --- | --- | --- |
+| `nat` | Mac의 공유 NAT 네트워크: 일반적으로 `192.168.65.0/24`, `--nat-peers off`인 머신은 `192.168.64.0/24`([머신 간 연결](peers.md) 참고) | vphoned가 게스트의 네트워크 설정에 기록합니다. 게이트웨이와 DNS는 Mac(`192.168.65.1` 또는 `192.168.64.1`)입니다. |
+| `tunnel` | 모든 사설 서브넷 | 터널 자체의 DHCP가 할당합니다. `--gateway`로 다른 주소를 지정하지 않으면 게이트웨이(DNS 확인자 역할도 함)는 서브넷의 첫 번째 주소입니다. |
+| `bridged` | 물리 네트워크의 주소 | vphoned가 게스트에 기록합니다. `--gateway`와 `--dns`는 해당 네트워크의 값으로 설정하세요. |
+
+> [!TIP]
+> 공유 `nat` 네트워크의 주소는 Mac의 DHCP 서버에 예약되지 않습니다. DHCP가 다른 가상 머신에 할당했을 가능성이 낮은 범위의 높은 쪽 주소(예: `.200`)를 고르세요.
+
+`nat` 모드에서는 머신이 참여하는 공유 네트워크의 주소여야 합니다. 서로 연결되는 머신(기본값)은 두 번째 네트워크(`192.168.65.0/24`), `--nat-peers off`인 머신은 첫 번째 네트워크(`192.168.64.0/24`)입니다. vmnet의 `Shared_Net_Address`가 옮겨졌다면 둘 다 이를 따릅니다. 그 밖의 서브넷에는 `tunnel`을 사용하세요.
+
+vphoned는 `vphone-vm`이 연결할 때마다 주소를 적용하므로, Mac이 모르는 사이에 게스트에서 바뀐 설정은 되돌려집니다. vphoned는 자신이 한 설정만 되돌립니다. 게스트의 설정 앱에서 직접 입력한 주소는 가상 머신이 DHCP로 돌아갈 때 건드리지 않습니다.
+
+macOS 26은 가상 머신에 전용 NAT 네트워크를 제공할 수 있지만, 그 서브넷은 가상 머신이 중지된 뒤에도 예약된 채로 남고(테스트에서 40분 뒤에도 예약 상태), 그동안 그 네트워크에서의 모든 시작이 실패하므로 vphone은 이를 사용하지 않습니다.
+
+## 함께 보기
+
+- [네트워크](overview.md)
+- [포트 포워딩](port-forwarding.md)
+- [머신 간 연결](peers.md)
diff --git a/Documents/ko/networking/names.md b/Documents/ko/networking/names.md
new file mode 100644
index 00000000..331f90ea
--- /dev/null
+++ b/Documents/ko/networking/names.md
@@ -0,0 +1,70 @@
+# 네트워크상의 이름
+
+이 페이지에서는 두 가지 이름을 다룹니다. Mac이 이름으로 게스트에 접근할 수 있게 하는 게스트 자신의 `.local` 이름, 그리고 게스트가 확인하는 이 Mac의 `.local` 이름입니다.
+
+## 게스트의 이름(mDNS)
+
+기본적으로 꺼져 있습니다. 켜면 이름으로 게스트에 접근할 수 있습니다.
+
+```sh
+vphone-cli vm config <name> --mdns on
+ping <vm-name>.local
+```
+
+| 설정 | 효과 |
+| --- | --- |
+| `--mdns on` | 게스트가 `<vm-name>.local`에 응답합니다. 가상 머신 이름에서 영문자와 숫자가 아닌 문자는 하이픈이 됩니다. `ipad_pro.13`은 `ipad-pro-13.local`이 됩니다. |
+| `--mdns <name>` | 게스트가 직접 고른 다른 이름에 응답합니다. |
+| `--mdns off` | 게스트 자신의 이름으로 돌아갑니다. |
+
+이 이름은 `none`을 포함한 모든 모드에서 동작합니다.
+
+| 모드 | `<name>.local`이 확인되는 주소 |
+| --- | --- |
+| `nat` | 공유 네트워크에서의 게스트 주소, 그리고 USB 링크 주소 |
+| `bridged` | LAN의 모든 기기에 대해 게스트의 LAN 주소, Mac에서는 USB 링크 주소도 |
+| `tunnel`, `none` | 게스트의 USB 링크 주소(Mac에서만) |
+
+게스트에는 네트워크 카드 외에도, USB로 연결된 iPhone이 Mac에 제공하는 것과 같은 네트워크 링크가 있습니다. Mac에서는 `169.254` 주소를 가진 `en` 인터페이스로 나타납니다. 이 주소는 링크 로컬이지만 Mac은 이 주소로 게스트에 직접 접근하므로, `tunnel` 모드에서도 `<name>.local`로 연결하면 포트 포워딩 없이 게스트의 서비스에 닿습니다.
+
+알아 둘 점:
+
+- 다른 기기가 이미 그 이름을 쓰고 있으면 mDNS가 게스트의 이름을 바꿉니다(`name-2`).
+- `vm rename`은 `--mdns on`이 가상 머신 이름에서 만든 이름을 바꿉니다. 직접 고른 이름은 유지됩니다.
+- `vm stop`이나 창 닫기로 중지한 가상 머신은 자신의 알림을 철회할 수 없습니다. Mac의 확인자는 캐시된 레코드가 만료될 때까지 이전 주소를 계속 반환하며, 호스트 주소의 경우 75분(TTL 4500초)입니다.
+
+vphoned는 `vphone-vm`이 연결할 때마다 게스트의 네트워크 설정(`LocalHostName`)에 이름을 설정하며, 게스트의 mDNSResponder가 자신의 모든 링크에서 이 이름을 알립니다.
+
+## 게스트에서의 이 Mac의 이름
+
+기본적으로 켜져 있습니다. 게스트는 이 Mac의 mDNS 이름(`scutil --get LocalHostName`에 `.local`을 붙인 것)을 게스트가 Mac에 접근하는 주소로 즉시 확인합니다.
+
+| 모드 | 게스트에서의 `<Mac>.local` |
+| --- | --- |
+| `nat` | 공유 네트워크의 Mac. 보통 `192.168.65.1`(`--nat-peers off`이면 `192.168.64.1`) |
+| `tunnel` | 게이트웨이. 기본값은 `192.168.127.1`입니다. QEMU와 VirtualBox의 `10.0.2.2`처럼, 이 주소로의 연결은 Mac의 루프백(`127.0.0.1`)에 도달합니다 |
+| `bridged` | 브리지된 인터페이스에서의 Mac 주소 |
+
+철회하려면 다음을 실행합니다.
+
+```sh
+vphone-cli vm config <name> --mac-name off
+```
+
+게스트의 확인자가 무엇을 반환하는지, 각 주소에 연결되는지 확인하려면 다음을 실행합니다.
+
+```sh
+vphone-launchpad-cli guest rpc <name> network.resolve '{"host":"<Mac>.local","family":"ipv4","port":8000}'
+```
+
+### 필요한 이유
+
+mDNS만으로는 게스트에서 Mac 이름의 IPv4 조회가 실패할 수 있었습니다. 게스트는 USB 링크에서도 Mac의 응답을 받는데, 그 링크에서 Mac에는 IPv4 주소가 없으므로 '해당 레코드 없음'으로 응답합니다. 먼저 응답한 링크가 조회 결과를 정했기 때문에, IPv4 주소가 필요한 앱은 다른 링크의 실제 응답이 캐시될 때까지 오류를 받았습니다. 또한 조회 결과에서 USB 링크의 Mac `169.254` 주소가 먼저 나왔습니다. iOS는 `169.254.0.0/16`을 기본 인터페이스로 라우팅하므로, 이 주소에 연결하는 일반 소켓은 아무도 응답하지 않는 `en0`으로 나가 시간 초과까지 기다릴 수 있었습니다.
+
+vphoned는 `/etc/hosts`의 한 줄처럼 게스트 자체의 mDNSResponder에 이 이름을 로컬 레코드로 등록합니다. 그러면 네트워크에 묻지 않고, 캐시된 응답도 쓰지 않고, IPv4 조회에 그 주소 하나로 즉시 응답합니다. `vphone-vm`이 연결할 때마다, 그리고 vphoned가 시작될 때 다시 등록하므로, 재시동 후 앱이 실행되기 전에 이름이 준비됩니다. 게스트의 시스템 볼륨은 읽기 전용이므로 `/etc/hosts` 자체는 수정하지 않으며, 어떤 네트워크에도 알리지 않습니다. IPv6 조회는 여전히 mDNS로 갑니다.
+
+## 함께 보기
+
+- [네트워크](overview.md)
+- [MAC 및 IP 주소](addresses.md)
+- [터널 모드](tunnel.md)
diff --git a/Documents/ko/networking/overview.md b/Documents/ko/networking/overview.md
new file mode 100644
index 00000000..0dadf392
--- /dev/null
+++ b/Documents/ko/networking/overview.md
@@ -0,0 +1,56 @@
+# 네트워크
+
+각 가상 머신에는 네트워크 모드가 하나 있습니다. 이 페이지에서는 모드를 고르는 방법과 실행 중인 가상 머신의 네트워크를 분리하는 방법을 설명합니다. 이 섹션의 다른 페이지에서는 터널 모드, 주소, 포트 포워딩, 이름, 머신 간 연결을 다룹니다.
+
+## 네트워크 모드
+
+| 모드 | 게스트가 인터넷에 연결되는 방식 | 사용하는 경우 |
+| --- | --- | --- |
+| `nat` | Virtualization.framework에 내장된 NAT | 기본값입니다. Mac에 VPN이 없거나, VPN이 게스트의 트래픽을 전달할 필요가 없을 때. |
+| `bridged` | Mac의 물리 인터페이스에 직접 연결되며, 그 네트워크에서 자체 주소를 가짐 | LAN의 다른 컴퓨터에서 게스트에 접근해야 할 때. |
+| [`tunnel`](tunnel.md) | `vphone-vm`이 Mac에서 여는 일반 연결을 통해 | Mac의 트래픽이 VPN이나 프록시 앱을 거치고, 게스트의 트래픽도 그 경로를 따라야 할 때. |
+| `none` | 네트워크 장치 없음 | 게스트를 오프라인으로 유지해야 할 때. |
+
+모드는 가상 머신의 `config.plist`에 저장되고 가상 머신이 시작될 때 읽히므로, 변경 사항은 다음 시작부터 적용됩니다.
+
+## 모드 선택하기
+
+Launchpad에서는 다음과 같이 합니다.
+
+1. 머신을 중지합니다.
+2. `⋯` 메뉴나 오른쪽 클릭 메뉴에서 Settings…를 선택합니다.
+3. Network 섹션에서 모드를 선택합니다.
+
+New Machine에서는 Advanced Options에서 모드를 설정합니다. 머신을 하나 선택하면 Settings…에 Address와 Port Forwarding 섹션도 있습니다.
+
+명령줄에서는 다음과 같습니다.
+
+```sh
+vphone-cli vm config <name> --network tunnel
+# or through Launchpad
+vphone-launchpad-cli exec vm config <name> --network tunnel
+```
+
+`tunnel`에는 `vphone-cli vm config --help`에 이 모드가 나열되는 `VPhone.bundle`이 필요합니다. 이전 번들은 이 설정을 거부합니다.
+
+## 실행 중인 가상 머신의 네트워크 분리하기
+
+`vm network`는 실행 중인 가상 머신에 작용하며, 변경 내용은 저장되지 않습니다.
+
+```sh
+vphone-cli vm network <name> # state of the NIC
+vphone-cli vm network <name> --link down # unplug the cable
+vphone-cli vm network <name> --link up # plug it back in
+```
+
+게스트에서는 링크가 끊겼다가 다시 연결되는 것으로 보입니다. 같은 요청을 `vphone.sock`에서 `{"t":"network"}`에 `"link":"down"` 또는 `"link":"up"`을 붙여 보낼 수도 있습니다.
+
+> [!NOTE]
+> 실행 중인 가상 머신은 다른 네트워크로 옮길 수 없습니다. Virtualization은 변경을 받아들인 뒤 내부 오류로 가상 머신을 중지하므로, `vm network`는 가상 머신이 시작할 때의 네트워크만 다시 연결합니다. 모드를 바꾸려면 `vm config`를 사용하고 가상 머신을 다시 시작하세요.
+
+## 함께 보기
+
+- [터널 모드](tunnel.md): VPN이나 프록시 앱을 사용하는 Mac
+- [MAC 및 IP 주소](addresses.md): 저장된 MAC, 이전 MAC이 차지한 임대, 고정 주소
+- [포트 포워딩](port-forwarding.md): Mac의 포트를 게스트로 전달하기
+- [네트워크상의 이름](names.md)과 [머신 간 연결](peers.md)
diff --git a/Documents/ko/networking/peers.md b/Documents/ko/networking/peers.md
new file mode 100644
index 00000000..195da8ab
--- /dev/null
+++ b/Documents/ko/networking/peers.md
@@ -0,0 +1,33 @@
+# 머신 간 연결
+
+한 Mac의 `nat` 머신들은 Bonjour를 포함해 서로 직접 연결됩니다. 가상 Apple Watch도 이 방식으로 가상 iPhone과 페어링합니다. 이 페이지에서는 머신 하나를 분리해 두는 방법을 설명합니다.
+
+## 머신 격리하기
+
+```sh
+vphone-cli vm config <name> --nat-peers off # isolate this guest again
+vphone-cli vm config <name> --nat-peers on # the default
+```
+
+Launchpad에서는 머신의 Network 설정에 있는 'Reach other NAT machines'입니다. 변경 사항은 다음 시작부터 적용됩니다.
+
+격리된 게스트는 Mac과 인터넷에는 연결되지만 다른 가상 머신에는 연결되지 않습니다. 격리는 각 머신 자체의 연결에 대한 설정이므로, 해제를 선택한 머신은 다른 머신의 설정과 관계없이 격리된 상태로 남습니다.
+
+## 머신이 속한 네트워크
+
+| 설정 | 공유 네트워크 | Mac의 주소 |
+| --- | --- | --- |
+| `--nat-peers on`(기본값) | `192.168.65.0/24` | `192.168.65.1` |
+| `--nat-peers off` | `192.168.64.0/24` | `192.168.64.1` |
+
+[고정 주소](addresses.md)(`--ip`)는 머신이 참여하는 네트워크에 있어야 합니다. 고정 주소가 첫 번째 네트워크(`192.168.64.0/24`)에 있는 머신은 다른 머신과의 연결을 요청하지 않는 한 격리된 상태로 남으며, 요청하면 두 번째 네트워크의 주소가 필요합니다.
+
+## 배경
+
+기본적으로 Virtualization.framework는 Mac의 공유 네트워크에서 각 `nat` 게스트를 다른 게스트와 격리합니다. vphone은 이 격리를 끄며, 그러면 vmnet이 서로 연결되는 머신들을 첫 번째 네트워크 다음 블록인 두 번째 공유 네트워크에 둡니다. 이 스위치는 Virtualization.framework의 비공개 기능입니다. 이 스위치가 없는 버전에서는 모든 게스트가 격리되며, 가상 머신이 시작될 때 그렇게 알려 줍니다.
+
+## 함께 보기
+
+- [네트워크](overview.md)
+- [MAC 및 IP 주소](addresses.md)
+- [네트워크상의 이름](names.md)
diff --git a/Documents/ko/networking/port-forwarding.md b/Documents/ko/networking/port-forwarding.md
new file mode 100644
index 00000000..2987eeb5
--- /dev/null
+++ b/Documents/ko/networking/port-forwarding.md
@@ -0,0 +1,40 @@
+# 포트 포워딩
+
+`nat`와 `tunnel` 모드에서 `--forward`를 사용하면 Mac의 포트를 게스트로 전달할 수 있습니다. `bridged`는 게스트를 자체 주소로 LAN에 연결하므로 포워딩이 필요하지 않습니다.
+
+## 포워딩 추가 및 제거
+
+```sh
+vphone-cli vm config <name> --forward tcp:8022:22
+vphone-cli vm config <name> --forward udp:0.0.0.0:5353:53
+vphone-cli vm config <name> --remove-forward 8022
+vphone-cli vm config <name> --clear-forwards
+```
+
+형식은 다음과 같습니다.
+
+```text
+[tcp|udp:][host-address:]host-port:guest-port
+```
+
+| 부분 | 의미 |
+| --- | --- |
+| `tcp` 또는 `udp` | 프로토콜 |
+| `host-address` | Mac에서 포워딩이 수신하는 주소. 기본값은 `127.0.0.1`이며, `0.0.0.0`으로 지정하면 LAN의 다른 기기에서도 접근할 수 있습니다. |
+| `host-port` | Mac의 포트 |
+| `guest-port` | 게스트의 포트 |
+
+포트를 더 추가하려면 `--forward`를 반복합니다. Launchpad에서는 머신의 Settings…에 Port Forwarding 섹션이 있습니다.
+
+## 포워딩 동작 방식
+
+- `vphone-vm`은 가상 머신이 시작될 때 리스너를 열고 중지될 때 닫습니다.
+- `nat` 모드에서는 게스트의 주소, 즉 [고정 주소](addresses.md)나 vphoned가 보고하는 주소로 연결합니다.
+- `tunnel` 모드에서는 연결이 게이트웨이에서 온 것처럼 게스트에 도달합니다.
+- Mac에서 이미 사용 중인 포트는 가상 머신의 로그에 보고되고 건너뜁니다. 다른 포워딩은 계속 동작합니다.
+
+## 함께 보기
+
+- [네트워크](overview.md)
+- [터널 모드](tunnel.md)
+- [MAC 및 IP 주소](addresses.md)
diff --git a/Documents/ko/networking/tunnel.md b/Documents/ko/networking/tunnel.md
new file mode 100644
index 00000000..3750a3cc
--- /dev/null
+++ b/Documents/ko/networking/tunnel.md
@@ -0,0 +1,66 @@
+# 터널 모드
+
+Mac의 트래픽이 VPN이나 프록시 앱을 거치고 게스트의 트래픽도 같은 경로를 따라야 할 때 `tunnel` 모드를 사용하세요. `nat`와 `bridged`에서는 게스트의 패킷이 VPN을 우회합니다.
+
+## 켜기
+
+머신을 중지한 뒤 다음을 실행합니다.
+
+```sh
+vphone-cli vm config <name> --network tunnel
+```
+
+Launchpad에서는 머신의 Settings…에 있는 Network 섹션에서 `tunnel`을 선택합니다. 번들의 `vphone-cli vm config --help`에 `tunnel`이 나열되어야 하며, 이전 번들은 이를 거부합니다.
+
+## 동작 확인하기
+
+1. 머신을 시작하고 부팅이 끝날 때까지 기다립니다.
+2. 게스트의 주소를 확인합니다.
+
+ ```sh
+ vphone-launchpad-cli guest rpc <name> device.network
+ ```
+
+ `en0`에 `192.168.127.3`이 표시되어야 합니다. `fe80::` 주소만 표시되면 DHCP가 아직 끝나지 않은 것입니다. 몇 초 기다린 뒤 다시 시도하세요.
+3. 게스트에서 페이지를 엽니다.
+
+ ```sh
+ vphone-launchpad-cli guest rpc <name> apps.open_url '{"url":"https://example.com"}'
+ ```
+
+4. Mac에서 연결이 `vphone-vm`에 속하고 VPN의 주소를 사용하는지 확인합니다.
+
+ ```sh
+ lsof -nP -a -i -p "$(pgrep -f 'vphone-vm.*<name>')"
+ ```
+
+## 게스트에서 보이는 것
+
+| 항목 | 값 |
+| --- | --- |
+| 게스트 주소 | DHCP로 받는 `192.168.127.3/24`, 또는 [고정 주소](addresses.md) |
+| 게이트웨이와 DNS | `192.168.127.1`, 또는 고정 주소 서브넷의 첫 번째 주소 |
+| MTU | 1500 |
+| DNS | `192.168.127.1`로 보낸 질의는 Mac의 확인자로 전달됩니다 |
+| 게이트웨이로의 다른 연결 | Mac의 루프백 `127.0.0.1`(TCP 및 UDP) |
+
+프록시 앱에서 게스트는 머신 이름을 딴 별도의 클라이언트로 표시되며, 앱의 규칙은 다른 앱과 마찬가지로 게스트에도 적용됩니다.
+
+## 제한 사항
+
+- **IPv4만 지원합니다.** 게스트는 IPv6 주소를 받지 않으며, IPv6 트래픽은 버려집니다.
+- **포워딩된 포트를 제외하면 아웃바운드만 가능합니다.** [포트 포워딩](port-forwarding.md)에 나열된 포트 외에는 Mac이나 LAN의 어떤 것도 이 네트워크로 게스트에 접근할 수 없습니다. USB 접근(`iproxy`, `ideviceinstaller`)과 `vphone.sock`은 게스트 네트워크를 사용하지 않으므로 계속 동작합니다. `.local` 이름도 USB 링크로 게스트에 도달합니다. [네트워크상의 이름](names.md)을 참고하세요.
+- **ping은 게이트웨이까지만 도달합니다.** 인터넷으로의 ICMP는 전달되지 않으므로, TCP와 UDP가 동작하더라도 게스트에서 `ping 1.1.1.1`은 실패합니다.
+- **처리량은 `vphone-vm`에 의해 제한됩니다.** 모든 패킷이 그 프로세스에서 처리됩니다. 다운로드와 동영상은 동작하지만, VPN이 없다면 `nat`가 더 빠릅니다.
+
+## 동작 원리
+
+VPN이 Mac의 기본 경로를 차지하고 있으면(WireGuard, Cloudflare WARP, 또는 Surge나 Clash처럼 TUN 모드로 동작하는 프록시 앱), `nat`와 `bridged`가 물리 인터페이스로 내보내는 패킷은 VPN을 건너뜁니다. 그 패킷은 암호화되지 않은 채 나가거나 아예 나가지 못합니다.
+
+`tunnel` 모드에서는 게스트의 네트워크 카드가 `vphone-vm` 안에 구현됩니다. 게이트웨이에 대한 DHCP, ARP, ping에 응답하고, 게스트의 각 TCP 연결과 UDP 흐름을 Mac의 일반 소켓으로 바꿉니다. 이 소켓은 다른 앱과 마찬가지로 Mac의 라우팅 테이블을 따르므로 VPN이 이를 전달합니다. root 권한, 새 네트워크 인터페이스, Mac의 네트워크 설정 변경이 모두 필요하지 않습니다.
+
+## 함께 보기
+
+- [네트워크](overview.md)
+- [MAC 및 IP 주소](addresses.md)
+- [포트 포워딩](port-forwarding.md)
diff --git a/Documents/ko/storage/library-and-backups.md b/Documents/ko/storage/library-and-backups.md
new file mode 100644
index 00000000..75b280e8
--- /dev/null
+++ b/Documents/ko/storage/library-and-backups.md
@@ -0,0 +1,69 @@
+# 보관함, 펌웨어, 백업
+
+vphone이 머신과 내려받은 펌웨어를 보관하는 위치, 그 위치를 옮기는 방법, 그리고 머신을 복사하고 백업하고 복원하는 방법을 설명합니다. 디스크 공간을 계획하거나, 보관함을 옮기거나, 머신의 사본이 하나 더 필요할 때 읽으세요.
+
+## 백업, 복사, 복원
+
+```sh
+vphone-cli vm list
+vphone-cli vm info myphone
+vphone-cli vm clone myphone copy # backup: same identity
+vphone-cli vm clone myphone second --new-identity # a second device
+vphone-cli vm export myphone --out myphone.tzst
+vphone-cli vm import myphone.tzst --name restored
+```
+
+`vm clone`은 중지된 머신을 복사하며, 가능하면 APFS의 쓰기 시 복사(copy-on-write)를 사용합니다. 원본이 실행 중이면 거부합니다.
+
+| 복제 | 식별 정보 | 용도 |
+| --- | --- | --- |
+| 일반 `vm clone` | 같은 머신 식별자와 MAC 주소 | 백업. 원본과 동시에 실행할 수 없습니다. |
+| `vm clone --new-identity` | 새 머신 식별자(ECID)와 그에 따른 새 UDID, 첫 시작 시 새 MAC 주소 | 원본과 동시에 실행하는 두 번째 기기 |
+
+`--new-identity` 사본은 다음과 같습니다.
+
+- 원본과 충돌하므로 고정 IPv4 주소, 포트 포워딩, 직접 지정한 mDNS 이름을 지웁니다. `--mdns on`이 원본의 이름에서 만든 mDNS 이름은 이름을 바꿀 때처럼 새 이름을 따릅니다. 필요하면 `vm config`로 새로 설정하세요.
+- 원본의 데이터, 앱, 설정을 그대로 유지하며 복원이 필요하지 않습니다.
+- `ideviceinstaller` 같은 lockdown 도구가 동작하려면 잠금을 해제하고 이 Mac을 다시 신뢰해야 합니다.
+- APFS에서는 원본과 디스크 블록을 공유하고 변경한 부분만 보관하므로 첫 부팅 후 약 0.35 GB를 차지합니다. 다만 `du`와 Finder는 각각을 전체 크기로 표시합니다.
+
+> [!WARNING]
+> `SEPStorage`, `nvram.bin`, 디스크 이미지를 머신끼리 바꾸지 마세요. 이들은 한 번의 복원으로 함께 만들어졌으며, SEP 저장소가 디스크와 맞지 않는 게스트는 부팅할 때 패닉합니다.
+
+## 파일 위치
+
+| 기본 경로 | 내용 |
+| --- | --- |
+| `~/.vphone/machines/<name>/` | 가상 머신 하나. 디스크, `config.plist`, 패치 작업 파일 포함 |
+| `~/.vphone/ipsws/` | 원격 소스 IPSW. 모든 가상 머신이 공유하며, 로컬 IPSW는 그 자리에서 읽습니다 |
+| `~/.vphone/gpu-drivers/<version>_<build>/` | cloudOS에서 추출한 GPU 드라이버 번들. 모든 가상 머신이 공유합니다 |
+| `~/.vphone/kernelcache/` | vphone600 구성 요소가 없는 cloudOS 릴리스용 kernelcache 믹스, 준비된 볼륨, 도너 추출물 |
+
+위치를 옮기려면 다음을 사용합니다.
+
+| 설정 | 옮기는 대상 |
+| --- | --- |
+| `VPHONE_ROOT` | `~/.vphone` 데이터 루트 전체: 머신 보관함과 캐시 |
+| `VPHONE_LIBRARY_ROOT` | 머신 보관함만. `VPHONE_ROOT`보다 우선합니다 |
+| `vm create`와 `fw prepare`의 `--ipsw-cache <dir>` | IPSW 캐시만 |
+
+## IPSW 캐시와 다운로드
+
+내려받은 IPSW는 삭제할 때까지 캐시에 남으므로, 같은 URL로 두 번째 머신을 만들 때는 아무것도 내려받지 않습니다. Launchpad에서는 **File > Downloaded IPSWs…**로 삭제합니다.
+
+준비된 복원 트리는 `--keep-artifacts`를 넘기지 않으면 `vm create`가 성공한 뒤 삭제됩니다. 이전 빌드에서 준비한 머신에는 `.ipsw-cache/` 디렉터리가 남아 있을 수 있습니다. 삭제해도 안전하며, `vm export`는 이를 제외합니다.
+
+원격 IPSW는 Apple의 CDN처럼 서버가 HTTP 범위 요청에 응답하면 네 개의 연결로 동시에 내려받습니다. 각 연결은 32 MB 세그먼트를 차례로 받으며, 끊긴 세그먼트는 멈춘 곳부터 이어 받습니다. `fw prepare`의 `--download-connections <n>`으로 연결 수를 1~16 사이에서 지정합니다. 1이면 IPSW를 하나의 스트림으로 내려받으며, 범위 요청을 무시하는 서버에서도 이렇게 동작합니다.
+
+## 디스크 공간과 메모리
+
+리소스를 많이 쓰는 생성 작업은 한 번에 하나씩 실행하세요. IPSW와 임시 복원 트리가 상당한 디스크 공간을 차지하며, 큰 캐시를 패치할 때 메모리를 많이 사용할 수 있습니다. 두 번째 머신을 시작하기 전에 여유 공간을 확인하세요.
+
+Launchpad는 해당하는 경우 CFW 작업 파일을 보관함이 있는 외장 볼륨에 둡니다. 단독으로 실행하는 `vphone-cli cfw install`은 기본적으로 `/private/var/tmp`를 사용하며, root 소유의 비공개 디렉터리를 지정하는 `--work-parent`를 받습니다.
+
+## 함께 보기
+
+- [스냅샷](snapshots.md)
+- [템플릿](templates.md)
+- [가상 머신 간 디스크 공간 공유](sharing-disk-space.md)
+- [머신 생성 및 실행](../machines/create-and-run.md)
diff --git a/Documents/ko/storage/many-machines.md b/Documents/ko/storage/many-machines.md
new file mode 100644
index 00000000..79174d6b
--- /dev/null
+++ b/Documents/ko/storage/many-machines.md
@@ -0,0 +1,61 @@
+# 여러 머신 만들기
+
+`vm create-bulk`는 plist에 기술된 모든 머신을 순서대로 만듭니다. 파일 하나로 실험실이나 CI용 머신 여러 대를 준비할 때 사용하세요.
+
+## 실행하기
+
+```sh
+vphone-cli vm create-bulk list.plist --dry-run # print each machine's vm create command
+vphone-cli vm create-bulk list.plist
+```
+
+`vm create`와 마찬가지로, 빌드가 필요한 머신이 있으면 `sudo`로 실행하세요.
+
+## 목록 작성하기
+
+```xml
+<dict>
+ <key>version</key> <integer>1</integer>
+ <key>defaults</key>
+ <dict>
+ <key>library-root</key> <string>~/vphone-lab</string>
+ <key>iphone-version</key> <string>26.1</string>
+ <key>preset</key> <string>presets/lab.plist</string>
+ <key>cpu</key> <integer>4</integer>
+ </dict>
+ <key>machines</key>
+ <array>
+ <dict><key>name</key> <string>ci-1</string></dict>
+ <dict><key>name</key> <string>ci-2</string></dict>
+ <dict>
+ <key>name</key> <string>fuzz</string>
+ <key>iphone-build</key> <string>23F77</string>
+ <key>iphone-version</key> <false/>
+ <key>no-template</key> <true/>
+ </dict>
+ </array>
+</dict>
+```
+
+- 각 키는 `vm create` 옵션의 긴 이름이며, 값은 문자열이나 정수, 플래그는 `true`, `keep-apps`는 배열입니다.
+- `defaults`는 모든 머신에 적용됩니다. 머신 자체의 키가 우선하며, `false`는 기본값을 지웁니다.
+- 상대 경로는 plist가 있는 폴더를 기준으로 해석됩니다.
+- `library-root`는 머신을 다른 보관함에 둡니다. 명령줄의 `-l`이 이 값보다 우선합니다.
+- 입력을 묻는 일이 없도록, 모든 머신은 펌웨어(`iphone-version`, `iphone-build`, 또는 `iphone-source`와 `cloudos-source`)나 `template`을 지정해야 합니다.
+
+## 실행 방식
+
+첫 머신을 만들기 전에 모든 머신을 `vm create`와 같은 방식으로 검사합니다. 머신은 순서대로 만들어지므로, 템플릿 키가 같은 머신들은 첫 번째 머신이 만든 템플릿에서 복제됩니다. 처음 실패하는 지점에서 실행이 중단됩니다.
+
+이미 있는 이름은 오류입니다. 두 플래그로 이를 바꿀 수 있으며, 함께 사용할 수는 없습니다.
+
+| 플래그 | 효과 |
+| --- | --- |
+| `--skip-existing` | 이름이 이미 있는 머신을 건너뛰므로, 중단된 실행을 다시 실행해 나머지를 만들 수 있습니다. 실패한 머신은 멈춘 상태 그대로 남으므로, 먼저 삭제하지 않으면 그 머신도 건너뜁니다. |
+| `--force-override` | 해당 머신을 만들기 직전에 기존 가상 머신을 삭제합니다. 실행 중인 가상 머신이나 가상 머신이 아닌 폴더는 거부합니다. |
+
+## 함께 보기
+
+- [템플릿](templates.md)
+- [템플릿 만들기와 찾기](template-building.md)
+- [머신 생성 및 실행](../machines/create-and-run.md)
diff --git a/Documents/ko/storage/shader-cache.md b/Documents/ko/storage/shader-cache.md
new file mode 100644
index 00000000..cf471582
--- /dev/null
+++ b/Documents/ko/storage/shader-cache.md
@@ -0,0 +1,64 @@
+# 영구 셰이더 캐시
+
+머신은 컴파일된 GPU 셰이더를 부팅 간에 유지하므로, 애니메이션은 처음 몇 번 실행할 때 셰이더가 컴파일되는 동안에만 끊깁니다. 기존 머신에서 캐시를 켜거나 초기화하려면 이 페이지를 읽으세요.
+
+Standard 프리셋으로 만든 새 머신은 Task3 커널 패치와 게스트 Metal 캐시 재사용을 자동으로 활성화합니다. 호스트는 캐시를 `<machine>/ShaderCache`(예: `~/.vphone/machines/Lychee/ShaderCache`)에 저장합니다. 실행 파일이 바뀌면 새 호스트 캐시 식별 정보를 받습니다.
+
+## 기존 머신에서 켜기
+
+이 기능이 포함된 Core Bundle을 설치하고, 중지된 머신을 그 번들에 연결합니다. 그런 다음 게스트 환경과 커널을 업데이트합니다. 두 업데이트 모두 게스트의 데이터를 유지하며, 복원이나 `fw patch`가 필요하지 않습니다.
+
+### Launchpad에서
+
+1. 머신의 동작 메뉴에서 **Update Guest Environment**를 선택합니다.
+2. 머신의 **Patches** 인스펙터에서 **Update Kernel**을 선택합니다.
+
+이제 Standard는 **GPU Task3 shader cache**를 자동으로 선택합니다. 머신별로 명시적으로 해제한 설정은 유지되므로, 패치 선택이 해제되어 있다면 먼저 편집기에서 활성화하세요.
+
+### Launchpad CLI로
+
+```sh
+# Replace <version> with the installed Core Bundle version from bundle list.
+vphone-launchpad-cli vm stop Lychee
+vphone-launchpad-cli vm set-bundle Lychee <version> --update-environment
+vphone-launchpad-cli cfw update-kernel Lychee
+vphone-launchpad-cli vm start Lychee --wait
+```
+
+- `--update-environment`는 게스트 라이브러리와 캐시 재사용 표시 파일을 다시 배포합니다.
+- `cfw update-kernel`은 `FirmwareOriginals`에 있는 원본 커널을 현재 선택으로 다시 패치하고 Preboot의 kernelcache를 교체합니다.
+
+Core Bundle 연결만 바꿔서는 설치된 커널이 업데이트되지 않습니다.
+
+### vphone-cli만으로
+
+머신을 끈 상태에서 새 번들의 명령을 root 권한으로 실행합니다.
+
+```sh
+sudo vphone-cli cfw update-environment Lychee
+sudo vphone-cli cfw update-kernel Lychee
+```
+
+`vphone-cli fw patches Lychee`는 대기 중인 패치를 표시합니다. 두 업데이트 명령 모두 머신의 현재 선택을 적용하며, 대기 중인 다른 게스트나 커널 변경도 함께 적용됩니다.
+
+### 원본 커널이 없는 이전 머신
+
+`FirmwareOriginals`에 원본 커널이 없는 머신은 먼저 새 번들로 `fw prepare`와 `fw patch`를 실행하여 대체용 복원 트리에 업데이트된 커널이 들어가게 해야 합니다. 그런 다음 `cfw update-kernel`을 실행합니다. `restore`는 실행하지 마세요.
+
+## 호스트 캐시 초기화
+
+머신을 중지한 뒤 `ShaderCache` 디렉터리를 삭제합니다. 다음에 시작하면 새 호스트 캐시로 시작합니다.
+
+게스트 Metal 캐시는 `Disk.img` 안의 별도 파일이므로, 호스트 캐시를 지운다고 해서 첫 실행 때의 끊김이 모두 재현되지는 않습니다.
+
+## 제한 사항
+
+- Task3는 cloudOS 26.4 커널에만 적용되며, tvOS 프리셋에서는 비활성화되어 있습니다.
+- macOS 27보다 이전의 호스트에서는 게스트가 호스트 자체의 최대 버전으로 협상하고 그 버전의 기능을 유지하므로, 호스트 캐시가 부팅마다 새로 만들어집니다.
+- 실행 검증은 macOS 27.0.1, cloudOS 26.4, iOS 27.0.1 및 26.6.2 게스트에서 이루어졌습니다. 이전 호스트는 실제로 실행하지 않고 프레임워크 코드로 확인했습니다.
+
+## 함께 보기
+
+- [코어 번들](../launchpad/core-bundles.md)
+- [Launchpad CLI](../launchpad/launchpad-cli.md)
+- [보관함, 펌웨어, 백업](library-and-backups.md)
diff --git a/Documents/ko/storage/sharing-disk-space.md b/Documents/ko/storage/sharing-disk-space.md
new file mode 100644
index 00000000..3731ac7c
--- /dev/null
+++ b/Documents/ko/storage/sharing-disk-space.md
@@ -0,0 +1,50 @@
+# 가상 머신 간 디스크 공간 공유
+
+`vm rebase`는 중지된 가상 머신의 동일한 디스크 블록을 다른 가상 머신이나 템플릿의 블록과 함께 한 번만 저장하게 합니다. 템플릿 없이 복원했거나 가져온 머신에서 디스크 공간을 되찾을 때 사용하세요.
+
+같은 IPSW로 따로 복원한 두 가상 머신은 디스크 이미지의 상당 부분이 같아도 디스크에서 아무것도 공유하지 않습니다. iOS 27.0 iPhone 두 대는 약 20 GB의 데이터 중 같은 위치에 약 8.6 GB의 동일한 바이트를 가지며, 대부분 시스템 볼륨입니다.
+
+## 가상 머신 리베이스하기
+
+1. 두 머신을 모두 중지합니다. 같은 APFS 볼륨에 있어야 합니다.
+2. 리베이스로 얼마나 절약되는지 확인합니다.
+
+ ```sh
+ vphone-cli vm rebase second --onto first --dry-run
+ ```
+
+3. 가상 머신이나 템플릿을 기준으로 리베이스합니다.
+
+ ```sh
+ vphone-cli vm rebase second --onto first
+ vphone-cli vm rebase second --onto 3f2a91c0d4e7
+ ```
+
+`--onto`는 가상 머신 이름 또는 `vm template list`의 템플릿 식별자(또는 그 고유한 접두사)를 받습니다. 이름이 둘 다에 일치하면 가상 머신이 우선합니다. `--dry-run`은 아무것도 쓰지 않고 공유될 양과 기록될 양을 보고합니다.
+
+이전 이미지가 해제될 때까지 기록되는 블록을 위한 여유 공간이 볼륨에 필요합니다.
+
+## 동작 방식
+
+리베이스는 기준 이미지의 APFS 복제본으로 `second`의 디스크 이미지를 다시 만들고, 다른 블록만 기록합니다. 이미지를 교체하기 전에 모든 바이트를 원본과 비교하므로, 게스트에는 완전히 같은 디스크가 보입니다.
+
+바뀌는 것은 디스크 이미지뿐입니다. `SEPStorage`, `nvram.bin`, `config.plist`, 기기 식별 정보는 그대로 유지됩니다. 템플릿을 기준으로 리베이스해도 템플릿은 그대로이며, 가상 머신이 그 템플릿의 복제본이 되지도 않습니다. `vm template show`에도 표시되지 않습니다.
+
+## 결과 읽기
+
+절약되는 양은 **newly shared** 수치입니다. 동일하지만 이미 디스크에서 같은 블록인 바이트는 **already shared**로 보고되며, 이를 리베이스해도 아무것도 해제되지 않습니다.
+
+한 템플릿에서 `vm create`로 만든 가상 머신들은 이미 그 블록을 공유하므로, 서로를 기준으로 또는 그 템플릿을 기준으로 리베이스해도 거의 해제되지 않습니다. 명령은 비교하기 전에 이를 알려 주며, 절약량이 0.1 GB 미만이면 다시 알려 줍니다. 리베이스할 가치가 있는 가상 머신은 템플릿 없이(`--no-template`) 복원했거나 가져온 것입니다.
+
+## 알아 둘 점
+
+- 다른 무엇도 이전 이미지의 블록을 붙잡고 있지 않을 때만 공간이 돌아옵니다. 가상 머신의 스냅샷과 그 가상 머신에서 만든 복제본은 블록을 유지하므로, 먼저 삭제하지 않으면 절약되지 않습니다.
+- `du`와 Finder는 여전히 각 이미지를 전체 크기로 계산합니다. 볼륨의 여유 공간(`df`)이 정확한 기준입니다.
+- 어느 가상 머신이든 디스크에 쓰면 두 이미지는 다시 달라집니다. 템플릿처럼 한 번도 부팅하지 않는 기준이 가장 좋으며, 나중에 다시 리베이스하면 달라진 부분을 되찾을 수 있습니다.
+- 리베이스가 중단되면 가상 머신은 바뀌지 않으며, 그 안에 숨겨진 `.rebase-*` 폴더가 남을 수 있습니다. 이 폴더는 삭제하세요.
+
+## 함께 보기
+
+- [템플릿](templates.md)
+- [스냅샷](snapshots.md)
+- [보관함, 펌웨어, 백업](library-and-backups.md)
diff --git a/Documents/ko/storage/snapshots.md b/Documents/ko/storage/snapshots.md
new file mode 100644
index 00000000..938f6a81
--- /dev/null
+++ b/Documents/ko/storage/snapshots.md
@@ -0,0 +1,65 @@
+# 스냅샷
+
+스냅샷은 중지된 머신의 디스크와 부팅 상태를 저장해 두었다가 나중에 되돌아갈 수 있게 합니다. 깨끗하게 설치한 직후 스냅샷을 만들고, 게스트에서 되돌리기 어려운 작업을 시도한 뒤 되돌리세요.
+
+## 만들기, 목록 보기, 되돌리기, 삭제
+
+1. 머신을 중지합니다. `vphone-cli vm stop myphone`을 실행하거나 창에서 닫습니다.
+2. 스냅샷을 만든 뒤 게스트에서 작업합니다. 저장한 상태로 돌아가려면 머신을 다시 중지하고 되돌립니다.
+
+```sh
+vphone-cli vm snapshot create myphone clean --note "fresh install"
+vphone-cli vm snapshot list myphone
+vphone-cli vm snapshot revert myphone clean
+vphone-cli vm snapshot delete myphone clean
+```
+
+- `revert`와 `delete`는 변경하기 전에 확인을 요청합니다. `--force`를 지정하면 묻지 않습니다.
+- 되돌려도 스냅샷은 남아 있으므로 다시 그 스냅샷으로 돌아갈 수 있습니다.
+- `list --json`은 `{"name", "created", "note"}` 객체 배열을 오래된 순서로 출력합니다. `created`는 ISO 8601 형식이며, 메모가 없으면 `note`는 생략됩니다.
+- `list`와 `delete`는 머신이 실행 중일 때도 동작하며, 둘 다 실행 중인 파일을 건드리지 않습니다.
+
+## 만들기나 되돌리기가 거부될 때
+
+`create`와 `revert`는 머신이 실행 중이거나, 어떤 프로세스든 디스크 이미지, `SEPStorage`, `nvram.bin`을 열고 있으면 거부합니다. 거부 메시지에는 파일을 열고 있는 각 프로세스의 이름이 표시됩니다. 그중 어느 것도 머신을 실행하는 프로세스가 아니라면(백업 도구, Spotlight 등) 그렇다고 알려 주며, 해당 프로세스가 파일을 닫은 뒤 다시 시도하면 성공합니다.
+
+머신이 APFS 볼륨에 있지 않을 때도 `create`는 수십 기가바이트에 이를 수 있는 디스크 이미지를 복사하지 않고 거부합니다.
+
+`Snapshot.plist`에 세 가지 상태 파일이 모두 나열되어 있지 않거나 스냅샷에 속하지 않는 파일이 나열된 스냅샷은, 아무것도 바꾸기 전에 손상된 것으로 거부됩니다.
+
+되돌리기는 전부 성공하거나 전부 실패합니다. 도중에 실패하면 머신의 원래 파일을 제자리에 돌려놓고 오류를 보고하므로, 머신은 이전 상태 그대로입니다. 드물게 원래 파일을 돌려놓는 것까지 실패하면 오류 메시지에 그렇게 표시됩니다. 이 경우 머신을 시작하기 전에 스냅샷으로 다시 되돌리세요.
+
+## 스냅샷에 포함되는 것
+
+| 포함 항목 | 이유 |
+| --- | --- |
+| 디스크 이미지(`Disk.img`) | 게스트의 시스템과 데이터 |
+| `SEPStorage`, `nvram.bin` | Secure Enclave 상태와 부트 체인의 NVRAM. 디스크와 일치해야 합니다 |
+| `PatchReceipt.plist` | 게스트에 적용된 패치 |
+| `restore-info.json` | 디스크의 iOS 버전과 `cfw install` 완료 여부 |
+
+디스크, `SEPStorage`, `nvram.bin`은 항상 함께 움직입니다. Secure Enclave의 재사용 방지 카운터는 `SEPStorage`에 있고 디스크에는 그에 맞는 상태가 있습니다. 서로 다른 시점의 디스크와 `SEPStorage`를 함께 쓰면 다음 부팅 때 SEP가 패닉합니다.
+
+`PatchReceipt.plist`와 `restore-info.json`은 있을 때만 저장됩니다. 스냅샷을 만들 때 없었던 파일은 되돌릴 때 삭제되므로, 기록은 나중의 설치가 아니라 복원된 디스크를 나타냅니다.
+
+다음은 포함되지 않으며, 되돌려도 바뀌지 않습니다.
+
+- `config.plist`: 기기 식별 정보, CPU, 메모리, 네트워크 등의 설정. 언제든 `vm config`로 변경할 수 있으며, 되돌리기는 이를 취소하지 않습니다.
+- 패치 선택(`PatchSelection.plist`), 복원 트리, `FirmwareOriginals/`, ROM. 이들은 게스트 상태가 아니라 Mac에 있는 입력입니다.
+- `launchpad.json`. Launchpad는 자체 사본을 스냅샷 폴더에 저장하고 직접 되돌려 놓습니다. CLI는 스냅샷 폴더에 있는 추가 파일을 건드리지 않으며, 스냅샷과 함께 삭제합니다.
+
+## 디스크 공간
+
+스냅샷은 `<vm>/Snapshots/<name>/`에 APFS 복제본으로 저장됩니다. 만들기는 즉시 끝나며 공간을 차지하지 않습니다. 게스트가 쓰기 전까지 머신과 스냅샷은 모든 블록을 공유하며, 쓴 뒤에는 바뀐 블록만 새로 공간을 차지합니다. `du`와 Finder는 각 스냅샷을 디스크 전체 크기로 계산하므로 실제 사용량보다 크게 표시합니다. 볼륨의 여유 공간이 정확한 기준입니다.
+
+스냅샷은 만들 때의 디스크 블록을 유지합니다. 해당 머신의 스냅샷이 이전 블록을 붙잡고 있는 동안에는 `vm rebase`로 공간이 확보되지 않습니다. [가상 머신 간 디스크 공간 공유](sharing-disk-space.md)를 참고하세요.
+
+## 복제, 내보내기, 이름 변경
+
+`vm clone`과 `vm export`는 스냅샷을 가져가지 않습니다. 복제본이나 가져온 머신은 스냅샷 없이 시작합니다. 머신을 삭제하거나 이름을 바꾸면 스냅샷도 함께 삭제되거나 이름이 바뀝니다.
+
+## 함께 보기
+
+- [보관함, 펌웨어, 백업](library-and-backups.md)
+- [가상 머신 간 디스크 공간 공유](sharing-disk-space.md)
+- [문제 해결](../help/troubleshooting.md)
diff --git a/Documents/ko/storage/template-building.md b/Documents/ko/storage/template-building.md
new file mode 100644
index 00000000..57ae8bc9
--- /dev/null
+++ b/Documents/ko/storage/template-building.md
@@ -0,0 +1,118 @@
+# 템플릿 만들기와 찾기
+
+가상 머신을 직접 템플릿으로 마무리하는 방법, `vm create`가 어떤 템플릿을 사용할지 확인하는 방법, Launchpad가 템플릿을 만드는 방식을 설명합니다. 템플릿이 무엇이고 키에 무엇이 포함되는지는 먼저 [템플릿](templates.md)을 읽으세요.
+
+## 가상 머신을 템플릿으로 마무리하기
+
+가상 머신을 만든 직후 템플릿으로 만들려면 중지하고, 정리하고, 설정 부팅을 거친 뒤 채택합니다. Launchpad가 템플릿을 만들어야 할 때 하는 작업과 같습니다.
+
+```sh
+vphone-cli vm stop phone-src
+vphone-cli vm template trim phone-src --tier standard # offline, no root; frees nothing until the setup boot
+vphone-cli vm template setup phone-src # headless; --window to watch, slimming switches as for vm create
+vphone-cli vm template adopt phone-src --iphone-source … --cloudos-source … # key from its records; the sources are recorded
+vphone-cli vm create phone-d --template <id> --skip-first-boot
+```
+
+### vm template setup
+
+- 실행 중인 가상 머신과 고정된 템플릿은 거부합니다.
+- 자체적으로는 아무것도 정리하지 않습니다. `vm template trim`이 기록한 단계를 유지하며, 다른 단계를 지정한 `--trim`은 거부합니다.
+- 가상 머신에서 vphoned가 제거하지 못한 앱이 있으면 이를 보고하고 기록되는 단계에서 제외하므로, 채택된 키는 실제로 수행된 작업을 나타냅니다.
+- `--strict`를 지정하면 대신 실패합니다. 아무것도 기록하지 않으며, 설정 부팅을 다시 실행할 수 있습니다. 같은 스위치에 대해 `vm template find`가 제공한 키로 `--expect`와 함께 가상 머신을 채택할 때 사용하세요.
+- `vm template list`에 표시된 `.building-…` 이름(설정 부팅이 실패한 `vm create`)을 지정하면, 빌드를 그 키에 맞게 설정하여 경량화 방식을 확정하고, 빌드가 오프라인 정리 전에 멈췄다면 먼저 정리를 실행하며, 성공하면 고정합니다.
+
+### vm template adopt
+
+| 옵션 | 효과 |
+| --- | --- |
+| `--iphone-source`, `--cloudos-source` | 템플릿을 만드는 `vm create`처럼, 가상 머신을 만들 때 사용한 IPSW를 `Template.plist`에 기록합니다. |
+| `--json` | 새 템플릿을 `vm template show --json`과 같은 형식으로 출력합니다. |
+| `--expect <id>` | 가상 머신의 기록이 템플릿 식별자 `<id>`를 제공하지 않으면 거부하고 가상 머신을 그대로 둡니다. `<id>`는 그 가상 머신을 만들 때 사용한 옵션으로 `vm template find`가 출력한 `id`입니다. |
+
+나중에 템플릿을 다시 찾아야 한다면 항상 `--expect`를 사용하세요. 이 옵션이 없으면 설정 부팅이 완전히 끝나지 않은(제거하지 못한 앱이 있는) 가상 머신이 다른 키로 저장되고, 이후 같은 옵션의 모든 `vm create`가 이를 찾지 못해 또 다른 템플릿을 만들게 됩니다.
+
+거부할 때 예상 키를 계산할 수 있으면 서로 다른 필드를 표시합니다. 보관함의 템플릿이나 빌드에 그 키가 있거나 경량화 방식만 다를 때 계산할 수 있습니다. 그렇지 않으면 비교할 수 있도록 가상 머신 자체의 키를 출력합니다. `--json`을 지정하면 거부 내용이 stdout에도 출력되며, 명령은 상태 1로 종료됩니다.
+
+```text
+{"adopted": false, "error": "unexpected_template", "id": …, "expected": …, "differences": […], …}
+```
+
+## 템플릿 찾기
+
+`vm template find`는 아무것도 내려받거나 복원하거나 변경하지 않고, 같은 옵션의 `vm create`가 어떤 템플릿에서 복제할지 알려 줍니다.
+
+```sh
+vphone-cli vm template find --iphone-source … --cloudos-source … [--device …] [--preset …] [--disk-size …] [--block <id>] [--allow <id>] [slimming switches] --json
+```
+
+키는 `vm create`와 같은 방식으로 계산합니다. 빌드 정보는 IPSW가 로컬 파일이거나 이미 IPSW 캐시에 있으면 IPSW에서, 그렇지 않으면 기록에 같은 두 소스가 있는 템플릿에서 가져오므로, IPSW를 삭제한 뒤에도(로컬 IPSW 포함) 키를 계산할 수 있습니다. `--block`과 `--allow`는 `fw set-patches`가 기록하는 것과 같은 패치별 재정의입니다.
+
+| JSON 필드 | 의미 |
+| --- | --- |
+| `resolved` | 키를 계산할 수 있었는지 여부 |
+| `resolvedBy` | `ipsw` 또는 `template` |
+| `id` | 템플릿 식별자 |
+| `summary` | 키 요약 |
+| `key` | 전체 키 |
+| `template` | 일치하는 템플릿. `vm template show --json` 형식이며, 최신이든 오래되었든 표시됩니다 |
+| `usable` | 템플릿이 존재하며 최신인지 여부 |
+| `building` | 생성 작업이 빌드 잠금을 갖고 있는지 여부 |
+| `reason` | 키를 계산할 수 없을 때 그 이유 |
+
+## Launchpad에서
+
+Launchpad 2.9 이상은 기본적으로 템플릿에서 머신을 만듭니다.
+
+### New Machine
+
+New Machine은 짧은 페이지로 열립니다. 이름, 펌웨어 카탈로그의 기기와 iOS 버전, **Slim System** 스위치가 있습니다. 그 아래 행은 나머지 설정을 요약하며, 네 페이지로 된 **Advanced Options**를 엽니다.
+
+- 하드웨어
+- 템플릿과 그 구성: 정리 단계와 유지할 언어, 서비스 프로필, 제거할 시스템 앱
+- Core Bundle, 사용자 지정 IPSW, 패치
+- 위치, 네트워크, 복원 옵션
+
+이 행은 기본값과 다른 설정의 개수를 세고, **Create**를 막는 항목이 있으면 그 이름을 표시합니다. **Create from a template**를 끄면 `--no-template`처럼 머신을 자체 키로, 경량화 없이 단독 복원합니다. Apple 계정 옵션은 제공되지 않습니다. 어느 쪽이든 게스트가 로그인을 거부하므로, 서비스 프로필이 trimmed일 때 Launchpad는 항상 `--accounts-off`를 넘깁니다. 시트는 페이지에 맞춰 600포인트까지 커지고 그 이상은 스크롤되므로, 노트북 화면에서도 버튼이 화면 안에 남습니다.
+
+### kernelcache를 다시 빌드하는 펌웨어
+
+**Firmware**에서 자체 cloudOS에서도 실행되는 릴리스(`fw catalog`의 세 번째 열)는 권장 cloudOS 옆에 그 cloudOS를 제공합니다. 이 경우 생성 작업은 사용자 권한으로 kernelcache 믹스를 준비하고 도우미가 root로 링크하게 하며, 이때 인증을 한 번 요청합니다.
+
+이전의 호환 Core Bundle(2.12.0)은 `ipsw` 도구로 믹스를 준비하므로, Launchpad는 이런 조합에 여전히 `ipsw` 도구 필드를 표시합니다. Core Bundle 2.12.1 이상은 네이티브로 추출하며 선택한 경로를 무시합니다.
+
+iPhone XS Max는 iOS 18.1~18.7.2를 각 릴리스 자체의 cloudOS에서 템플릿 없이 실행하며, 기본 프리셋은 Minimal입니다. Standard도 동작합니다(18.6에서 확인). 이 조합은 항상 kernelcache를 다시 빌드하므로 **Firmware**에서 macOS 빌더도 묻습니다.
+
+- 원격 로그인이 켜져 있고 macOS 15 또는 26.0~26.3을 실행하는 Mac이나 macOS 가상 머신의 `user@host`
+- ssh와 sudo에 사용할 암호. ssh 키와 암호 없는 sudo를 사용하면 비워 둡니다.
+
+Launchpad는 빌더는 저장하지만 암호는 저장하지 않으며, 암호는 환경 변수(`VPHONE_KMUTIL_SSH_PASSWORD`)로만 `vphone-cli`에 전달됩니다. 그런 다음 생성 작업은 ssh를 통해 사용자 권한으로 믹스를 준비하고 링크합니다. macOS 26.4부터는 빌더가 필수이며, 빌더가 없는 이전 Mac에서는 도우미가 root로 믹스를 링크합니다.
+
+### 생성 작업이 템플릿을 사용하는 방식
+
+생성 작업은 먼저 `vm template find`를 실행합니다.
+
+- 일치하는 최신 템플릿이 있으면 머신을 복제하고(`vm create --template <id> --skip-first-boot`) 부팅합니다.
+- 없으면 같은 보관함에 `template-`와 16진수 여덟 자리로 된 이름의 임시 머신을 만들어 템플릿을 빌드합니다. 일반적인 단계(복원, 그리고 도우미를 통한 `cfw install`)를 실행한 뒤 `vm template trim`, 헤드리스 `vm template setup --strict`, `vm template adopt --iphone-source … --cloudos-source … --expect <id>`를 실행하고, 그 결과에서 머신을 복제합니다.
+
+제거해야 할 앱이 남아 있으면 설정 부팅이 실패하고, 빌드의 키가 `find`가 계산한 키와 다르면 채택이 실패하므로, 이후 생성 작업이 찾지 못할 id로 빌드가 저장되는 일은 없습니다. 각각은 소요 시간이 표시되는 별도의 단계이며, 실패한 단계에는 `vphone-cli`가 제공한 이유가 표시됩니다.
+
+New Machine의 **Patch Settings**에서 지정한 패치별 재정의는 템플릿 키와 같은 방식으로 나뉩니다.
+
+- 부트 체인 재정의는 키에 포함됩니다. 템플릿은 그 재정의를 적용해 빌드되며, `find`도 그 재정의가 적용된 템플릿을 찾습니다.
+- 게스트 패치 재정의는 키에 포함되지 않습니다. 템플릿은 그 재정의 없이 빌드됩니다. 복제 후 생성 작업은 첫 부팅 전에 `fw set-patches`로 새 머신에 재정의를 기록하고, 도우미를 통해 `cfw update-environment`로 적용합니다(**Apply guest patches** 단계). 따라서 템플릿이 한 생성 작업의 게스트 패치 선택을 다른 생성 작업에 넘기는 일은 없습니다.
+
+템플릿을 빌드한 뒤에는 생성 작업이 원본 IPSW 두 개를 삭제할지 묻습니다. 확인 없이는 아무것도 삭제하지 않습니다.
+
+### Launchpad에서 템플릿 관리하기
+
+- **File > Templates…**는 모든 보관함의 템플릿을 머신, 경량화 방식, 크기, 상태와 함께 나열하며, 템플릿을 삭제할 수 있습니다.
+- **Guest System…**(머신의 Actions 메뉴와 인스펙터에 있음)은 실행 중인 머신의 서비스 프로필을 전환하고, 템플릿이 제거한 시스템 앱을 되돌립니다.
+- 인스펙터와 머신 목록에는 각 머신의 파일이 할당한 공간 옆에 그 머신만 사용하는 디스크 공간이 표시됩니다. 다른 머신이나 템플릿이 공유하지 않는 블록으로, 머신을 삭제하면 해제됩니다. 그 전에 만들어진 로컬 Time Machine 스냅샷은 만료될 때까지 블록을 유지합니다.
+
+## 함께 보기
+
+- [템플릿](templates.md)
+- [여러 머신 만들기](many-machines.md)
+- [펌웨어 준비](../firmware/firmware-preparation.md)
+- [Launchpad CLI](../launchpad/launchpad-cli.md)
diff --git a/Documents/ko/storage/templates.md b/Documents/ko/storage/templates.md
new file mode 100644
index 00000000..692d3363
--- /dev/null
+++ b/Documents/ko/storage/templates.md
@@ -0,0 +1,162 @@
+# 템플릿
+
+템플릿은 `vm create`가 새 머신을 복제해 내는 완성되고 고정된 머신입니다. 특정 옵션 조합으로 처음 생성할 때 템플릿이 만들어지며, 이후 같은 옵션으로 생성하면 몇 초 만에 끝나고 아무것도 내려받지 않습니다. 템플릿을 만들고, 경량화하고, 정리하는 방식을 제어하려면 이 페이지를 읽으세요.
+
+## 템플릿에서 머신 만들기
+
+`vm create`는 기본적으로 템플릿을 사용합니다.
+
+```sh
+vphone-cli vm create phone-a --iphone-source … --cloudos-source … # builds the template, clones phone-a
+vphone-cli vm create phone-b --iphone-source … --cloudos-source … # clones phone-b, no restore
+vphone-cli vm create phone-c --template 3f2a91c0d4e7 --cpu 4 --memory 6144
+```
+
+- 일치하는 템플릿이 있으면 `vm create`는 새 식별 정보로 머신을 복제하고, 요청한 CPU, 메모리, 네트워크를 지정한 뒤, 한 번 부팅하여 vphoned를 확인합니다. root 권한도 IPSW도 필요하지 않습니다.
+- 없으면 필요에 따라 IPSW를 내려받고, 준비 폴더에서 전체 파이프라인을 실행하여 템플릿을 만들고 고정한 뒤, 그 템플릿에서 머신을 복제합니다.
+- `--template <id>`는 식별자 또는 네 자리 이상의 고유한 접두사로 지정한 템플릿에서 복제하며, IPSW 옵션을 받지 않습니다. `--device`, `--preset`, `--disk-size`와 경량화 스위치를 지정하면 템플릿과 일치해야 합니다. 복제본에서는 이를 바꿀 수 없습니다.
+- `--no-template`은 머신을 자체 키로 단독 복원하며, 경량화 스위치를 받지 않습니다.
+
+가상 머신을 직접 템플릿으로 만들거나, `vm create`가 어떤 템플릿을 사용할지 확인하거나, Launchpad가 템플릿을 만드는 방식을 보려면 [템플릿 만들기와 찾기](template-building.md)를 읽으세요.
+
+## 템플릿을 일치시키는 방법
+
+무엇이든 복원하기 전에 `vm create`는 옵션과 두 IPSW로 템플릿 키를 계산합니다. 키에는 다음이 포함됩니다.
+
+- 게스트 기기
+- iOS 및 cloudOS 버전과 빌드
+- 패치 프리셋과 그 프리셋이 결정하는 부트 체인 패치. 번들에 포함되지 않은 프리셋(프리셋 파일 또는 `~/.vphone/patches_presets`에 있는 프리셋)이라면 게스트 패치를 포함해 그 프리셋이 결정하는 모든 패치가 포함됩니다. 이런 프리셋은 같은 식별자로도 내용이 바뀔 수 있고, 복제본은 템플릿의 게스트 패치를 그대로 유지하기 때문입니다.
+- 번들 시리즈(2.9.x라면 `2.9`)
+- 디스크 크기
+- 게스트의 System 볼륨에서 정리하는 항목(`--trim`)과 유지하는 언어
+- 아래의 경량화 스위치
+
+CPU, 메모리, 화면, 네트워크는 키에 포함되지 않습니다.
+
+빌드 정보는 IPSW가 로컬 파일이거나 이미 IPSW 캐시에 있으면 IPSW에서 가져옵니다. 그렇지 않으면 `vm template find`가 계산하는 방식대로, 같은 두 소스로 기록된 템플릿에서 가져옵니다([템플릿 만들기와 찾기](template-building.md)의 '템플릿 찾기' 참고). 삭제된 로컬 IPSW는 없는 것으로 간주합니다.
+
+### 템플릿 만들기
+
+일치하는 템플릿이 없으면 전체 파이프라인이 `.templates/.building-<id>-<uuid>/`에서 실행됩니다. `cfw install`, 오프라인 정리, 설정 부팅 순서입니다. 결과는 고정된 뒤 한 번에 `<library>/.templates/<id>/`로 이름이 바뀝니다.
+
+- 복원 트리는 `--keep-artifacts`와 관계없이 고정 전에 삭제됩니다. 약 11 GB에 달하는 복원 트리가 템플릿이 존재하는 동안 계속 남게 되는데, 어떤 복제본도 이를 사용할 수 없기 때문입니다. `--keep-artifacts`는 `--no-template`과 함께 쓸 때만 복원 트리를 보존하며, `vm template adopt`도 이를 삭제합니다.
+- 같은 키로 두 번째 `vm create`를 실행하면 두 번째 사본을 복원하지 않고 첫 번째가 끝나기를 기다립니다.
+- 실패한 빌드는 조사할 수 있도록 준비 폴더에 남습니다.
+
+템플릿은 만들어지는 동안 설정 부팅을 위해 한 번 부팅하며, 고정된 뒤에는 다시 부팅하지 않습니다.
+
+## 오프라인 정리
+
+`cfw install` 후 템플릿 빌드는 게스트가 전혀 사용하지 않는 시스템 파일을 System 볼륨에서 삭제합니다. 이 작업은 볼륨을 호스트에 마운트하여 오프라인으로 진행합니다. `vm create`의 `--trim`(기본값 `standard`)과 `vm template trim`의 `--tier`로 단계를 선택합니다.
+
+| 단계 | 삭제 대상 | 크기 |
+| --- | --- | --- |
+| `none` | 없음 | |
+| `conservative` | `usr/standalone/update`의 내용(소프트웨어 업데이트 램디스크, 베이스밴드 펌웨어) | 0.35 GB |
+| `standard` | conservative에 더해 AirPods/Beats 페어링 에셋(`PreinstalledAssetsV2/RequiredByOs/com_apple_MobileAsset_SharingDeviceAssets`), 시계 페이스(`NanoTimeKit/FaceBundles`), 유지하지 않는 모든 언어의 `LinguisticData/RequiredAssets_*.bundle` | 1.2 GB |
+| `aggressive` | 예약됨: 게스트에서 검증될 때까지 거부됩니다 | |
+
+`--keep-languages`(기본값 `en,zh-Hans,zh`, 영어는 항상 유지)로 `standard`가 유지할 언어를 선택합니다. 단계, 목록의 버전, 유지할 언어는 템플릿 키(`standard/1/en,zh,zh-Hans`)에 포함되므로, 다르게 정리된 템플릿은 서로 일치하지 않습니다.
+
+> [!WARNING]
+> 정리는 되돌릴 수 없습니다. 복제본에서 파일을 되찾을 수 없습니다.
+
+삭제한 파일은 처음에는 공간을 확보하지 않습니다. 게스트의 원래 시스템 스냅샷(`cfw install`이 남긴 `orig-fs.disabled.rn-*`)이 여전히 모든 블록을 붙잡고 있으며, 호스트에서는 root로도 이를 삭제할 수 없습니다. 설정 부팅이 첫 단계로 이를 삭제해야 비로소 공간이 반환됩니다. 그래서 설정 부팅을 하지 않는 템플릿에는 정리가 거부되며, 정리된 템플릿은 스냅샷이 사라진 뒤에만 고정하거나 채택할 수 있습니다.
+
+`vm template trim`에는 root 권한이 필요하지 않습니다. 템플릿에서 복제되지 않은 중지된 머신이나 완료되지 않은 `.building-…` 폴더에서 실행되며, 고정된 템플릿은 거부합니다.
+
+## 설정 부팅과 경량화
+
+설정 부팅은 모든 복제본이 시작해야 할 상태로 템플릿을 마무리합니다. 템플릿을 한 번 부팅하고 vphoned를 통해 다음을 순서대로 수행합니다.
+
+1. `cfw install`이 남긴 `orig-fs.disabled.rn-*` APFS 스냅샷을 삭제합니다(약 20 MB에 더해, 삭제될 때까지 System 볼륨에서 정리한 모든 파일을 붙잡고 있습니다).
+2. 설정 지원을 건너뜁니다(`setup.skip`).
+3. 첫 부팅 작업이 안정될 때까지 기다립니다(`setup.settle`, 최대 10분). 첫 부팅 때 installd가 제거 가능한 시스템 앱을 펼칩니다.
+4. 시스템 앱을 제거합니다(`apps.remove_system`, 백업은 게스트에 보관).
+5. 서비스 프로필을 적용합니다(`services.profile.apply`). 여기에는 로그인 후속 데몬(`followupd`, `appleidsetupd`)을 끄는 것도 포함됩니다.
+6. 재시동한 뒤 확인합니다. 스냅샷이 남아 있지 않은지, 설정이 완료되었는지, 프로필의 서비스가 실행 중이지 않은지, 제거한 앱이 사라졌는지, vphoned가 응답하는지 확인합니다.
+7. 이 부팅을 위해 `vphone-vm`이 고정한 기기 이름을 지우고 게스트를 정상적으로 종료합니다.
+
+각 단계에는 제한 시간이 있습니다. 단계가 실패하면 가상 머신을 중지하고 아무것도 기록하지 않으며 빌드를 고정하지 않은 상태로 둡니다. `vm create`는 실패한 단계와 다시 시도하는 방법을 알려 줍니다.
+
+| 스위치 | 기본값 | 효과 |
+| --- | --- | --- |
+| `--slim on\|off` | on | `off`는 아무것도 정리하지 않고 모든 앱과 서비스를 유지합니다. 설정 부팅은 여전히 실행되어 설정 지원을 건너뛰고 스냅샷을 삭제합니다. |
+| `--trim none\|conservative\|standard` | standard | 위의 오프라인 정리입니다. |
+| `--keep-languages <list>` | `en,zh-Hans,zh` | `--trim standard`가 유지할 언어입니다. |
+| `--service-profile trimmed\|none` | trimmed | vphoned의 trimmed 프로필: App Store 데몬과 로그인 후속 데몬을 포함해 약 140개의 launchd 작업을 끕니다. 이 프로필을 사용하는 iPhone은 Apple Watch와 페어링할 수 없습니다(`Research/Guest/watch_pairing.md` 참고). |
+| `--remove-apps on\|off` | on | App Store, 홈, TV, 뉴스, FaceTime, iTunes Store, 메시지, 게임, 나의 찾기, 지갑을 제거합니다. 카메라와 전화는 남습니다. |
+| `--keep-apps <ids>` | 없음 | 위 목록 중 유지할 번들 ID, 쉼표로 구분(`com.apple.findmy,com.apple.Passbook`). |
+| `--accounts-off` | off | `akd`, `amsaccountsd`, `appleaccountd`도 끕니다. 그러면 게스트에서 Apple 계정에 로그인할 수 없습니다. |
+
+각 선택은 키에 포함되므로, 경량화 방식이 다른 템플릿이 나란히 존재하며 각 템플릿은 그 방식을 요청한 생성에만 사용됩니다. 서비스 프로필의 제한은 [Watch 페어링 기록](../../../Research/Guest/watch_pairing.md)을 참고하세요.
+
+제거한 앱과 프로필은 복제본에서 `vphone-launchpad-cli guest rpc` 또는 Launchpad의 **Guest System**으로 되돌릴 수 있습니다.
+
+- `apps.restore_system`은 백업에서 앱을 되돌려 놓습니다.
+- `services.profile.apply {"profile":"none"}`은 프로필이 끈 것을 정확히 다시 켭니다.
+
+### 복제본이 물려받는 것
+
+복제본은 템플릿에서 다음을 물려받습니다. 완료된 설정, 설정 부팅이 남긴 상태의 앱과 서비스, installd와 인덱서가 수행한 첫 부팅 작업, 그리고 그 부팅 시점의 Data 볼륨입니다.
+
+기기 이름은 물려받지 않습니다. 템플릿의 고정된 이름은 지워지므로, 복제본은 자신의 가상 머신이 연결하여 복제본의 이름을 고정할 때까지 `iPhone`으로 표시됩니다. 새 식별 정보를 가지므로 Mac에서 '이 컴퓨터를 신뢰하겠습니까?'를 다시 묻습니다.
+
+## 공유되는 비밀 정보
+
+> [!WARNING]
+> 한 템플릿에서 복제된 모든 머신은 템플릿은 물론 복제본끼리도 SEP 루트 비밀, Data 볼륨 키, 그리고 복원과 설정 부팅이 기록한 데이터를 공유합니다. 원리상 한 복제본이 다른 복제본의 Data 볼륨을 복호화할 수 있습니다.
+
+여러 기기를 이용한 연구를 위해 Apple 서비스에 로그인하는 경우처럼 자체 키가 필요한 머신은 `--no-template`으로 만들어야 합니다.
+
+복제본은 `vm clone --new-identity`와 마찬가지로 첫 시작 때 새 ECID, UDID, MAC 주소를 받습니다. APFS에서는 변경되지 않은 모든 블록을 템플릿과 공유합니다. 새 복제본은 쓰기를 시작하기 전까지 거의 공간을 차지하지 않으며, 경량화된 템플릿에서는 첫 부팅 때 쓸 작업도 적습니다.
+
+## 템플릿 관리
+
+```sh
+vphone-cli vm template list # id, key summary, STALE with the reasons
+vphone-cli vm template show <id> --json
+vphone-cli vm template trim myphone --tier standard # trim a stopped VM before adopting it
+vphone-cli vm template setup myphone # the setup boot, on a stopped VM
+vphone-cli vm template adopt myphone # freeze a stopped, newly created VM into a template
+vphone-cli vm template delete <id>
+```
+
+### 오래된 템플릿
+
+이 `vphone-cli`가 다른 번들 시리즈에 속하거나, 키가 이전 형식이거나, 프리셋이 이제 다른 부트 체인 패치로 결정되거나, 패치 영수증이 계획과 일치하지 않으면 템플릿은 오래된(stale) 것으로 표시됩니다. 오래된 템플릿은 사용되지 않으며, 그 키로 `vm create`를 실행하면 해당 템플릿을 지목하며 실패합니다. 다음 `vm create`가 새 템플릿을 만들게 하려면 오래된 템플릿을 삭제하세요.
+
+### 가상 머신 채택하기
+
+`vm template adopt <vm>`은 중지된 가상 머신을 그 자체 기록이 제공하는 키로 템플릿으로 만듭니다. 기록은 `restore-info.json`, `PatchPlan.plist`, `config.plist`, 디스크 이미지, Launchpad의 `launchpad.json`, 그리고 `vm template trim`과 `vm template setup`이 `Template.plist`에 기록한 단계입니다. 이 가상 머신은 `vm list`에서 사라집니다.
+
+가상 머신은 설정 부팅 직후에 채택하세요. 그 이후 게스트가 한 일은 모든 복제본이 물려받습니다. 스냅샷이 있는 가상 머신은 거부되며, 오래된 템플릿이 될 가상 머신도 `--force`를 지정하지 않으면 거부됩니다.
+
+### 고정된 템플릿은 부팅하지 않습니다
+
+`vm launch`와 `vphone-vm`은 DFU를 포함해 고정된 템플릿의 부팅을 거부합니다. 어떤 머신 이름으로도 `.templates` 안을 가리킬 수 없으므로 `vm launch`, `clone`, `export`, `rename`, `delete`가 실수로 템플릿을 선택하는 일은 없습니다. 고정된 뒤 템플릿이 부팅하면 이후의 모든 복제본이 물려받을 블록에 상태를 기록하게 되고, 그 전에 만든 복제본은 더 이상 블록을 공유하지 않게 됩니다.
+
+### 템플릿을 사용하는 머신
+
+템플릿에서 복제된 머신은 `TemplateSource.plist`에 템플릿을 기록합니다. 그 머신을 `vm clone`하면 기록이 유지되고(사본도 템플릿의 블록을 공유하므로), `vm export`는 기록을 제외합니다(가져온 머신은 아무것도 공유하지 않으므로). 기록에는 템플릿의 빌드도 들어 있으므로, 템플릿을 삭제하고 같은 키로 다시 만들면 이전 템플릿에서 복제된 머신은 새 템플릿의 블록을 전혀 공유하지 않으므로 사용 중인 머신으로 계산되지 않습니다.
+
+`vm template list`와 `show`는 각 템플릿을 사용하는 머신과 디스크상의 크기를 표시하고, `vm info`는 머신의 템플릿을 표시합니다. `vm delete`가 아직 존재하는 템플릿에서 복제된 마지막 머신을 삭제하면 그 사실을 알려 주며, 템플릿 자체는 절대 삭제하지 않습니다.
+
+```text
+note: template 3f2a91c0d4e7 (~17.40 GB) is no longer used by any machine; remove it with `vphone-cli vm template delete 3f2a91c0d4e7`
+```
+
+### 템플릿 삭제하기
+
+`vm template delete <id>`는 템플릿을 삭제하며, 그 템플릿에서 복제된 머신은 계속 동작합니다. 머신이 아직 템플릿과 공유하는 블록은 그 머신이 블록을 변경하거나 삭제될 때만 해제되므로, 복제본이 남아 있는 동안 템플릿을 삭제하면 템플릿 크기보다 적은 공간이 확보됩니다.
+
+출력되는 메모는 어느 경우에 해당하는지 알려 줍니다. 템플릿을 사용하는 머신이 있어 공유 블록이 그 머신이 변경하거나 삭제될 때까지 할당된 채로 남는 경우, 또는 현재 템플릿을 사용하는 머신이 없어 삭제하면 블록이 해제되는 경우입니다. 템플릿이 존재할 때 만들어진 로컬 Time Machine 스냅샷은 만료될 때까지 블록을 유지할 수 있습니다. `--json`과 `--force`를 함께 지정하면 같은 정보를 출력합니다.
+
+템플릿은 `vm list`에 표시되지 않지만 디스크 공간을 차지합니다. `~/.vphone/machines/.templates`를 확인하고, `du`는 템플릿과 각 복제본을 모두 전체 크기로 계산한다는 점에 유의하세요.
+
+## 함께 보기
+
+- [템플릿 만들기와 찾기](template-building.md)
+- [여러 머신 만들기](many-machines.md)
+- [가상 머신 간 디스크 공간 공유](sharing-disk-space.md)
+- [보관함, 펌웨어, 백업](library-and-backups.md)
diff --git a/Documents/zh/README.md b/Documents/zh/README.md
new file mode 100644
index 00000000..83cface7
--- /dev/null
+++ b/Documents/zh/README.md
@@ -0,0 +1,70 @@
+# vphone 使用手册
+
+初次使用 vphone?请先阅读[概览](get-started/overview.md),然后按照[快速开始](get-started/quick-start.md)操作。
+
+## 入门
+
+| 页面 | 用途 |
+| --- | --- |
+| [概览](get-started/overview.md) | vphone 是什么、需要什么,以及随附的各个程序 |
+| [快速开始](get-started/quick-start.md) | 用 Launchpad 或编程 Agent 创建第一台虚拟机 |
+| [宿主机设置](get-started/host-setup.md) | Mac 上的 SIP、AMFI 和 Research Guests 设置 |
+| [下载](get-started/downloads.md) | 已公证的 Launchpad 版本及匹配的 `VPhone.bundle` 版本 |
+
+## 虚拟机
+
+| 页面 | 用途 |
+| --- | --- |
+| [创建与运行](machines/create-and-run.md) | 在终端中创建、启动和停止虚拟机 |
+| [启动 ROM](machines/boot-roms.md) | 在 OpenAVB/OpenSEP 与 Apple 的 ROM 之间切换 |
+| [自动化 API](machines/automation-api.md) | 可选的本机 HTTP 和 WebSocket 接口 |
+| [设备名称与时钟](machines/device-name-and-clock.md) | 客户机从虚拟机名称和 Mac 时钟获取哪些信息 |
+| [软件包环境](machines/package-environment.md) | 在客户机中安装和删除软件包管理器 |
+
+## 固件与设备
+
+| 页面 | 用途 |
+| --- | --- |
+| [兼容性](firmware/compatibility.md) | 已验证的 iPhone 与 cloudOS 固件组合 |
+| [固件准备](firmware/firmware-preparation.md) | GPU 驱动恢复,以及较新 cloudOS 的 kernelcache 组合 |
+| [其他 iPhone 机型](firmware/iphone-models.md) | 使用其他 iPhone 机型的 IPSW 运行 iOS |
+| [iPadOS 客户机](firmware/ipados.md) | 运行 iPadOS 而非 iOS |
+
+## 存储与备份
+
+| 页面 | 用途 |
+| --- | --- |
+| [资料库与备份](storage/library-and-backups.md) | 虚拟机和缓存的存放位置、克隆与导出 |
+| [快照](storage/snapshots.md) | 保存已停止虚拟机的磁盘,并还原到该状态 |
+| [模板](storage/templates.md) | 一次恢复,供多台虚拟机复用 |
+| [构建模板](storage/template-building.md) | 把虚拟机制作成模板,以及查找模板 |
+| [共享磁盘空间](storage/sharing-disk-space.md) | 对分别恢复的虚拟机使用 `vm rebase` |
+| [批量创建虚拟机](storage/many-machines.md) | 从 plist 运行 `vm create-bulk` |
+| [着色器缓存](storage/shader-cache.md) | 为现有虚拟机启用持久的着色器缓存 |
+
+## 网络
+
+| 页面 | 用途 |
+| --- | --- |
+| [网络模式](networking/overview.md) | 选择模式,为运行中的虚拟机断开网络 |
+| [隧道模式](networking/tunnel.md) | Mac 使用 VPN 或代理 App 时 |
+| [MAC 与 IP 地址](networking/addresses.md) | 保存的 MAC 地址、旧租约、固定地址 |
+| [端口转发](networking/port-forwarding.md) | 把 Mac 上的端口转发到客户机 |
+| [网络上的名称](networking/names.md) | 客户机的 `.local` 名称,以及客户机中 Mac 的名称 |
+| [虚拟机互访](networking/peers.md) | 位于同一共享网络中的 `nat` 虚拟机 |
+
+## Launchpad 与 Bundle
+
+| 页面 | 用途 |
+| --- | --- |
+| [Launchpad 命令行](launchpad/launchpad-cli.md) | 用 `vphone-launchpad-cli` 操作 Launchpad |
+| [Core Bundle 与本地构建](launchpad/core-bundles.md) | 把虚拟机绑定到 bundle,测试本地构建 |
+| [Bundle 集成](launchpad/bundle-integration.md) | `VPhone.bundle` 包含什么,以及 App 如何使用它 |
+
+## 帮助
+
+| 页面 | 用途 |
+| --- | --- |
+| [故障排查](help/troubleshooting.md) | 启动被拒、恢复失败、客户机问题 |
+
+实现说明、补丁记录和完整的 API 参考见[研究记录](../../Research/README.md),仅提供英文版。
diff --git a/Documents/zh/firmware/compatibility.md b/Documents/zh/firmware/compatibility.md
new file mode 100644
index 00000000..40f9a9ab
--- /dev/null
+++ b/Documents/zh/firmware/compatibility.md
@@ -0,0 +1,166 @@
+# 固件兼容性
+
+哪些客户机固件与 cloudOS 的组合已知可以在哪些宿主机上启动。为新虚拟机选择版本之前,或者创建失败、想知道该组合是否测试过时,请查看本页。
+
+要查看当前目录在你的 Mac 上提供哪些版本,请运行:
+
+```sh
+vphone-cli fw catalog
+```
+
+> [!NOTE]
+> 从 v2.0.0 开始,vphone 只启动 `config.plist` 中 `schemaVersion=2` 的虚拟机。旧版本创建的虚拟机请用 `vm create` 重新创建;不支持原地升级。下面的结果描述的是已测试的组合,而非与旧虚拟机 bundle 的兼容性。
+
+## 已测试的环境
+
+以下是用原生 JB 流程完整跑通的 iPhone17,3 组合。两行 PR #486([PR #486](https://github.com/Lakr233/vphone-cli/pull/486))进入了锁定屏幕并响应了 vphoned ping;另外一次全新的 26.6.2 `vm create` 也完成了所有阶段,并在首次启动 ping 后成功退出。
+
+| 验证来源 | iPhone 恢复 IPSW | PCC/cloudOS IPSW | 观察结果 |
+| --- | --- | --- | --- |
+| PR #486 | `17,3_26.6.2_23G90` | `26.4-23E5207q` | JB 补丁、恢复、CFW、启动、vphoned ping |
+| PR #486 | `17,3_27.0_24A435` | `26.4-23E5207q` | JB 补丁、恢复、CFW、启动、vphoned ping |
+| 研究主板 | `17,3_26.6_23G71` | `26.6-23G71` | 从 CLI 使用 standard 和 Minimal 预设,从 Launchpad 使用 standard 预设(2026-10-20):转换设备树和 SEP、kernelcache 组合、恢复、CFW、启动、vphoned ping |
+| 研究主板 | `17,3_26.5_23F77` | `26.5-23F75` | 从 CLI 使用 standard 预设(2026-10-20):GPU 驱动取自临时 cloudOS 恢复、kernelcache 组合、恢复、CFW、启动、vphoned ping |
+| 研究主板 | `17,3_26.4_23E246` | `26.4-23E244` | 从 CLI 使用 standard 预设(2026-10-20):GPU 驱动取自临时 cloudOS 恢复、kernelcache 组合、恢复、CFW、启动、vphoned ping |
+| 研究主板 | `Watch7,18_26.4_23T240` | `26.4-23E244` | 从 CLI 和 Launchpad 使用 `watchos` 预设(2026-10-20):手表 kernelcache 组合、恢复、启动、vphoned ping |
+| 研究主板 | `11,6_18.7.2_22H124` | `18.7.2-22H43` | 从 CLI 使用 Minimal 预设(2026-10-21):GPU 驱动取自临时 cloudOS 恢复,iOS 18 kernelcache 组合通过 ssh 由 macOS 15.6.1 的 kmutil 链接、恢复、启动、vphoned ping;已检查屏幕、锁定屏幕、解锁和主屏幕手势 |
+| 研究主板 | `11,6_18.1_22B83` | `18.1-22B83` | 从 CLI 使用 Minimal 预设(2026-10-21):GPU 驱动取自临时 cloudOS 恢复,kernelcache 组合通过 ssh 由 macOS 15.6.1 的 kmutil 链接、恢复、启动、vphoned;已检查“你好”屏幕、锁定屏幕、解锁和主屏幕手势 |
+| 研究主板 | `11,6_18.5_22F76` | `18.5-22F76` | 从 CLI 使用 Minimal 预设(2026-10-21):GPU 驱动取自临时 cloudOS 恢复,kernelcache 组合通过 ssh 由 macOS 15.6.1 的 kmutil 链接、恢复、启动、vphoned;已检查锁定屏幕、解锁和主屏幕手势 |
+| 研究主板 | `11,6_18.6_22G86` | `18.6-22G86` | 从 Launchpad 的 CLI 使用 standard 预设(2026-10-24):kernelcache 组合(缓存)、恢复、CFW、启动、vphoned、“你好”屏幕;在允许两个 Frida 补丁的情况下,Frida 17.24.3 的 attach、spawn、Interceptor 和 Stalker 均可用 |
+
+### 使用哪个 cloudOS
+
+除非有特别的理由,请使用 cloudOS 26.4 beta(`26.4-23E5207q`)。它是包含 `vphone600ap` 的最新 cloudOS,客户机的内核、SEP 和设备树都来自这一身份,而且除了 `vphone-cli` 之外不需要任何其他东西。
+
+之后的所有 cloudOS(2026-10-03 核查)都只列出 PCC 主板和 `vresearch101ap`:`SupportedProductTypes` 中已没有 `iPhone99,11`,也没有 `kernelcache.*.vphone600`、`sep-firmware.vphone600` 或 `DeviceTree.vphone600ap`。在这类 cloudOS 上由研究主板代替(Research Board 补丁集):
+
+- `fw patch` 把研究主板的设备树和 SEP 转换为 vphone600 的版本,并按照该 kernelcache 的配方,用 vphone600 的虚拟化 kext 重新构建它的 kernelcache。
+- KDK 提取在本机原生完成;只有链接需要 root 权限(`vphone-cli fw kernelcache`)。见 [kernelcache 配方](../../../VPhoneExecutable/VPhoneVirtualization/Resources/kernelcache_recipes/README.md)和[固件准备](firmware-preparation.md)。
+- 没有配方覆盖的 cloudOS 会被 `fw prepare` 拒绝。
+- `fw catalog` 会在推荐的 cloudOS 旁列出每个 iOS 版本自己的 cloudOS,Launchpad 在 **Firmware**(固件)下提供它。
+
+| cloudOS | `vresearch101ap` | `vphone600ap` | kernelcache 配方 |
+| --- | --- | --- | --- |
+| `26.4-23E5207q` (beta) | 有 | 有 | 不需要 |
+| `26.4-23E244` | 有 | 无 | 有 |
+| `26.4.1-23E254` | 有 | 无 | 无 |
+| `26.5-23F75` | 有 | 无 | 有 |
+| `26.5.2-23F83` | 有 | 无 | 无 |
+| `26.6-23G71` | 有 | 无 | 有 |
+| `26.6.1-23G82` | 有 | 无 | 无 |
+| `26.7-23H20` | 有 | 无 | 有 |
+
+其他 iPhone 和 iPad 版本或许可以与 `26.4-23E5207q` 配合使用,但尚未通过同样的完整检查。
+
+### iOS 18 客户机
+
+iOS 18.1 到 18.7.2 运行在各自版本的 cloudOS 上,用户空间来自 iPhone XS 系列的 IPSW:
+
+- 用 `vm create --device iPhone11,6` 创建。默认使用 Minimal 预设;`--preset standard` 已在 18.6 上验证。
+- `fw catalog --device iPhone11,6` 会列出这些版本。
+- 它们的内核是 kernel-first 布局。从 macOS 26.4 起,需要由另一台运行 macOS 15 或 26.0 到 26.3 的 Mac 或 macOS 虚拟机通过 ssh 链接组合(`VPHONE_KMUTIL_SSH`;见[固件准备](firmware-preparation.md))。
+- Launchpad 以 iPhone XS Max 的名义提供它们,并以那台 Mac 作为 macOS 构建机。
+
+18.1、18.5 和 18.7.2 已在虚拟机上验证;其他四个配方尚未启动过。
+
+### iOS 27.0.1 上的 iPhone17,3
+
+iOS 27.0.1(24A446)在 bundle 2.5.0 及更早版本上首次启动失败(2026-10-04 复现,使用未修改的 Apple launchd 也一样):TXM 的 selector-24 预检查在 init 阶段拒绝所有二进制文件,启动时以 `unexpected SIGKILL of init` panic。`txm-boot-precheck_admission` 补丁修复了这个问题(见[研究记录](../../../Research/Firmware/txm_selector24_cms_gate.md))。打上补丁后,`26.4-23E5207q` 上的 iPhone17,3 27.0.1 可以启动到客户机,并响应 vphoned 的 `device.info`(当天验证)。bundle 2.6.0 是第一个包含该补丁的版本。
+
+## macOS 26.6.2 宿主机
+
+于 2026-10-23 使用 Core Bundle 2.12.1 验证,2026-10-24 又使用 Core Bundle 2.12.2 再次验证,宿主机为 Mac mini M4(Mac16,10,16 GB,macOS 26.6.2 25G83)。每台虚拟机都从零开始通过 CLI 创建。研究主板组合以普通用户身份准备 kernelcache 组合,用 sudo 链接,然后运行 `sudo vphone-cli vm create`。“默认”表示 `fw catalog` 在这台 Mac 上为该设备给出的最新组合,也就是 Launchpad 的 New Machine 会选择的组合。之后每台虚拟机都以无界面方式启动两次:vphoned 有响应,`device.info` 报告了正确的版本,客户机的串口日志中没有 panic。
+
+| 客户机 | 固件 | cloudOS | 结果 |
+| --- | --- | --- | --- |
+| iPhone17,3 | iOS 27.0.1(默认) | `26.4-23E5207q` | 构建模板、克隆、两次启动 |
+| iPhone18,2 | iOS 27.0.1(默认) | `26.4-23E5207q` | 构建模板、克隆、两次启动 |
+| iPad16,1 | iPadOS 27.0.1(默认) | `26.4-23E5207q` | 构建模板、克隆、两次启动 |
+| iPhone17,3 | iOS 26.6.2 | `26.4-23E5207q` | 构建模板、克隆、两次启动 |
+| iPhone17,3 | iOS 26.6.2 | `26.6-23G71` | 研究主板:原生 KDK 提取,macOS 26 链接后无残留 auth stub,28 个 kernelcache 补丁,两次启动 |
+| iPhone17,3 | iOS 26.5 | `26.5-23F75` | 研究主板,同上 |
+| iPhone17,3 | iOS 26.4 | `26.4-23E244` | 研究主板,同上 |
+| iPhone17,3 | iOS 18.6.2 | `26.1-23B85` | 构建模板、克隆、两次启动 |
+| iPhone11,6 | iOS 18.7.2(默认) | `18.7.2-22H43` | Minimal,组合通过 ssh 由 macOS 15.7.7 虚拟机的 kmutil 链接,两次启动 |
+| iPhone11,6 | iOS 18.6 | `18.6-22G86` | 同上:该配方的首次启动 |
+| iPhone11,6 | iOS 18.7 | `18.7-22H20` | 同上:该配方的首次启动 |
+| Watch7,18 | watchOS 26.4(默认) | `26.4-23E244` | `watchos` 预设,手表 kernelcache 组合,两次启动 |
+| AppleTV5,3 | tvOS 26.6(默认) | `26.4-23E5207q` | `tvos` 预设,两次启动 |
+| AppleTV14,1 | tvOS 26.6(macOS 26 上的默认) | `26.4-23E5207q` | `tvos-4k` 预设,26.6 OTA 用户空间,两次启动 |
+| AudioAccessory5,1 | HomePod 软件 27.0(macOS 26 上的默认) | `26.4-23E5207q` | `homepod-mini` 预设,两次启动 |
+| AppleTV14,1 | tvOS 27.0 | — | 下载前即被拒绝:需要 macOS 27 |
+| AudioAccessory5,1 | HomePod 软件 27.2 | — | 下载前即被拒绝:需要 macOS 27 |
+
+tvOS 27.0(24J361)和 HomePod 软件 27.2(24K120)的 OTA 使用 LZRAVEN 压缩负载,只有 macOS 27 能够解压。在较旧的 Mac 上,`fw catalog` 不会列出它们,因此 Launchpad 为这些设备提供的默认版本是 tvOS 26.6 和 HomePod 软件 27.0;如果指定其中任何一个,会在下载任何内容之前被拒绝。
+
+Apple TV 4K(第 4 代),即 `AppleTV18,1` / `J265AP`,目前仅供早期适配,使用 tvOS 27.2 beta(`24K120`):它的完整 OTA 叠加在 Apple TV HD 26.6 恢复基础和 cloudOS 26.4 beta(`23E5207q`)之上。它需要 macOS 27 和 `tvos-4k` 预设。2026-10-24,一台虚拟机完成了恢复和自定义固件安装,并两次冷启动到 vphoned 和旧版 TVSetup 的 4K 语言屏幕;设置本身没有完成。它不在上面的测试表中。见[适配记录](../../../Research/Firmware/tvos_support.md#apple-tv-4k-4th-generation)。
+
+cloudOS 26.7(23H20)没有可以搭配的 iPhone 版本。使用 iOS 26.6.2 的用户空间准备时,它的组合可以链接,28 个 kernelcache 补丁也都能应用,但 CFW 补丁 `_vm_fault_enter_prepare` 在该内核中找不到补丁位置。它尚未启动过。
+
+> [!TIP]
+> `vphone-escalator` 把允许列表保存在 amfid 的内存中,因此 amfid 重启时允许列表会丢失;这些宿主机在测试中途就发生过一次。AMFI 拒绝 bundle 时,Launchpad 会重新允许它。使用 CLI 时,请再次运行 `host preflight` 打印的 `vphone-escalator allow` 命令。
+
+## 其他 iPhone 机型
+
+iPhone17,3 以外的机型见[其他 iPhone 机型](iphone-models.md)。
+
+| 宿主机 | iPhone 恢复 IPSW | PCC/cloudOS IPSW | 观察结果 |
+| --- | --- | --- | --- |
+| Mac17,9 (M5 Pro) 27.0.1 | `18,1_26.6.2_23G90` (iPhone 17 Pro) | `26.4-23E5207q` | Launchpad `vm create`(2.5.1 本地 bundle):准备、补丁、恢复、CFW、启动到主屏幕,402x874 pt @3x,`model` 为 iPhone18,1,vphoned ping |
+| Mac17,9 (M5 Pro) 27.0.1 | `18,2_27.0.1_24A446` (iPhone 17 Pro Max) | `26.4-23E5207q` | 打上 `kernel-boot-shared_region_size` 补丁后**可以启动**(2026-10-06,bundle 2.6.0-local.0d5e6f90):`dyld cache mapped system-wide`,0 次 panic,vphoned 报告版本为 27.0.1,主屏幕为 440x956 pt @3x |
+| Mac17,7 (M5 Max) 26.4 | `19,2_27.0.1_24A446` (iPhone 18 Pro) | `26.4-23E5207q` | 集成 ARM64E_X1 兼容后**可以启动**(2026-10-17):离线恢复无错误,根卷封印验证通过,vphoned ping,“设置”、Safari 浏览器和“计算器”均可打开 |
+
+### iOS 27 上的 iPhone18,1 和 iPhone18,2
+
+这两款需要 `kernel-boot-shared_region_size` 补丁([issue #596](https://github.com/Lakr233/vphone-cli/issues/596),27.0 和 27.0.1)。自 2026-10-06 起,`standard` 预设在 iOS 27 基础系统上默认开启它。
+
+它们在 27.0.1 上的 dyld 共享缓存记录的 `sharedRegionSize` 为 `0x185804000`,大于 cloudOS 26.4 客户机内核的 `0x180000000` 共享区域,因此即使 `dyld-boot-maxslide` 取消了滑动,缓存也无法映射。没有这个补丁时,launchd 会在首次启动时以 `Library not loaded: /usr/lib/libSystem.B.dylib` panic。iPhone17,3 的 27.0.1 缓存(`0x17D508000`)仍然放得下。
+
+该补丁把 arm64 区域扩大到 `0x1C0000000`,这是不超过 26.4 内核自身任务映射上限的最大值。当虚拟机的内核带有该补丁时(其 `PatchReceipt.plist` 中会注明),`cfw install` 会按扩大后的区域衡量缓存,因此这些设备可以安装和启动;这已在上文的 iPhone18,2 27.0.1 上验证。
+
+没有该补丁时(bundle 较旧,或取消勾选了该补丁),`cfw install` 会拒绝这样的缓存并给出上述说明,而不是留下一个会 panic 的客户机。iOS 27 请使用 iPhone17,3,这些设备请使用 iOS 26。
+
+## iPadOS
+
+iPad 客户机见 [iPadOS 客户机](ipados.md)。
+
+| 宿主机 | iPad 恢复 IPSW | PCC/cloudOS IPSW | 观察结果 |
+| --- | --- | --- | --- |
+| Mac17,9 (M5 Pro) 27.0.1 | `iPad16,1,iPad16,2_26.6.2_23G90` | `26.4-23E5207q` | 准备、补丁、恢复、CFW(2.2.5 辅助程序)、启动到 iPadOS 主屏幕,744x1133 pt @2x,`model` 为 iPad16,1,vphoned ping |
+| Mac17,9 (M5 Pro) 27.0.1 | `iPad16,1,iPad16,2_27.0.1_24A446` | `26.4-23E5207q` | 从目录用 Launchpad 运行 `vm create --device iPad16,1`(2.4.0 bundle):准备、补丁、恢复、CFW、启动到 iPadOS 主屏幕,744x1133 pt @2x,`model` 为 iPad16,1,`ios_version` 为 27.0.1,vphoned ping |
+
+## 早期报告的组合
+
+以前的 README 记录了以下宿主机与固件组合。它们早于当前的单一模式流程,或者缺少同等的 vphoned 验收证据,因此请把它们视为研究历史,而不是当前的支持矩阵。
+
+| 宿主机 | iPhone | CloudOS |
+| --------------- | --------------------- | --------------- |
+| Mac16,11 27.0b2 | `17,3_18.6.2_22G100` | `26.1-23B85` |
+| Mac16,8 26.5.1 | `17,3_26.0_23A341` | `26.1-23B85` |
+| Mac16,8 26.5.1 | `17,3_26.0.1_23A355` | `26.1-23B85` |
+| Mac16,12 26.3 | `17,3_26.1_23B85` | `26.1-23B85` |
+| Mac16,12 26.3 | `17,3_26.3_23D127` | `26.1-23B85` |
+| Mac16,12 26.3 | `17,3_26.3_23D127` | `26.3-23D128` |
+| Mac16,12 26.3 | `17,3_26.3.1_23D8133` | `26.3-23D128` |
+| Mac16,11 26.2 | `17,3_26.4_23E246` | `26.4-23E5207q` |
+| Mac16,11 26.2 | `17,3_26.5_23F77` | `26.4-23E5207q` |
+| Mac16,11 27.0b2 | `17,3_26.5.2_23F84` | `26.4-23E5207q` |
+| Mac16,6 26.4.1 | `17,3_26.6_23G71` | `26.4-23E5207q` |
+| Mac16,11 27.0b2 | `17,3_26.6.1_23G83` | `26.4-23E5207q` |
+| Mac16,6 26.6.1 | `17,3_26.6.2_23G90` | `26.4-23E5207q` |
+| Mac16,11 27.0b2 | `17,3_27.0_24A5380h` | `26.4-23E5207q` |
+| Mac16,6 26.4.1 | `17,3_27.0_24A5390f` | `26.4-23E5207q` |
+| Mac16,6 26.6.1 | `17,3_27.0_24A5408d` | `26.4-23E5207q` |
+| Mac16,11 27.0b2 | `17,3_27.0_24A5418b` | `26.4-23E5207q` |
+| Mac16,11 27.0b2 | `17,3_27.0_24A5424a` | `26.4-23E5207q` |
+| Mac16,11 27.0b2 | `17,3_27.0_24A5430a` | `26.4-23E5207q` |
+| Mac16,6 26.6.1 | `17,3_27.0_24A435` | `26.4-23E5207q` |
+
+全部补丁及各自的适用范围见[补丁清单](../../../Research/0_binary_patch_comparison.md)。
+
+## 另请参阅
+
+- [固件准备](firmware-preparation.md)
+- [其他 iPhone 机型](iphone-models.md)
+- [iPadOS 客户机](ipados.md)
+- [创建与运行虚拟机](../machines/create-and-run.md)
diff --git a/Documents/zh/firmware/firmware-preparation.md b/Documents/zh/firmware/firmware-preparation.md
new file mode 100644
index 00000000..b6b16dc6
--- /dev/null
+++ b/Documents/zh/firmware/firmware-preparation.md
@@ -0,0 +1,71 @@
+# 固件准备
+
+在为固件打补丁之前,`vm create` 和 `fw prepare` 会如何处理两个 IPSW,以及不含 vphone600 组件的 cloudOS 还需要哪些额外步骤。手动运行各个阶段、复用 GPU 驱动,或者用研究主板组合创建虚拟机时,请参阅本页。
+
+## GPU 驱动
+
+`fw prepare` 需要先从 cloudOS 中取得半虚拟化 GPU 驱动,才能构建混合的 iPhone 恢复包。获取方式如下:
+
+1. 创建一台没有网络设备的临时 vphone 虚拟机,并以 DFU 模式启动。
+2. 用 vphone 自己的恢复后端把所选的 cloudOS IPSW 恢复到这台虚拟机中。
+3. 以只读方式装载恢复后的 System 宗卷,提取 GPU bundle。
+4. 删除临时虚拟机。
+
+提取出的 bundle 按 cloudOS 构建版本缓存在 `~/.vphone/gpu-drivers/` 中,因此之后使用同一 cloudOS 的虚拟机会跳过临时恢复。
+
+要复用之前提取的 bundle,请把它传给 `vm create` 或 `fw prepare`:
+
+```sh
+vphone-cli fw prepare myphone \
+ --gpu-driver-bundle /path/to/AppleParavirtGPUMetalIOGPUFamily.bundle
+```
+
+CLI 会把该 bundle 的 iPhoneOS 平台版本与所选 cloudOS 版本进行核对。每次恢复都会在线获取自己的票据。
+
+bundle 中还附带一个 arm64e GPU 编译器插件。`fw prepare` 会在打补丁和安装之前把它拷贝到准备好的 GPU bundle 中。
+
+## 研究主板组合
+
+26.4 beta 之后的 cloudOS 不含 vphone600 组件,因此由研究主板代替(见[兼容性](compatibility.md))。它的 kernelcache 会用 vphone600 的虚拟化 kext 重新构建。KDK 提取以你的身份原生运行;只有 kmutil 链接需要 root 权限。
+
+1. 照常运行 `fw prepare`。
+2. 以你自己的身份准备组合:
+
+ ```sh
+ vphone-cli fw kernelcache myphone
+ ```
+
+3. 以 root 身份链接:
+
+ ```sh
+ sudo vphone-cli fw kernelcache myphone
+ ```
+
+4. 继续运行 `fw patch`,它会从缓存中取用组合。
+
+`fw kernelcache` 旧的 `--ipsw` 参数仍可传入,但会被忽略。
+
+## 在另一台 Mac 上链接
+
+内核只能以 Apple 链接时所用的布局启动,而 kmutil 会采用它所运行的 Mac 的布局:
+
+| 宿主机 macOS | 可链接 |
+| --- | --- |
+| macOS 26.4 及更新版本 | iOS 26.4 及更新版本的 kernelcache(kernel-last) |
+| macOS 15,以及 26.0 到 26.3 | 较旧的 kernelcache(kernel-first),例如 iOS 18 |
+
+如果这台 Mac 的布局不符,可以由另一台 Mac 或 macOS 虚拟机通过 ssh 链接组合。为 `fw kernelcache` 或创建流程设置以下变量:
+
+```sh
+export VPHONE_KMUTIL_SSH='user@host'
+export VPHONE_KMUTIL_SSH_PASSWORD='password' # only without ssh keys and passwordless sudo there
+```
+
+准备好的宗卷会上传到那台 Mac 的 `/private/var/tmp`,在那里以 root 身份链接,然后删除。这台 Mac 上不需要任何 root 权限。另一台 Mac 必须打开“远程登录”,并且该用户必须能够使用 sudo。
+
+## 另请参阅
+
+- [固件兼容性](compatibility.md)
+- [创建与运行虚拟机](../machines/create-and-run.md)
+- [资料库、固件与备份](../storage/library-and-backups.md)
+- [kernelcache 配方](../../../VPhoneExecutable/VPhoneVirtualization/Resources/kernelcache_recipes/README.md)
diff --git a/Documents/zh/firmware/ipados.md b/Documents/zh/firmware/ipados.md
new file mode 100644
index 00000000..36e09f3d
--- /dev/null
+++ b/Documents/zh/firmware/ipados.md
@@ -0,0 +1,96 @@
+# iPadOS 客户机
+
+如何在 vphone 虚拟机中运行 iPadOS 而非 iOS。需要 iPad 的用户空间、屏幕尺寸或多任务处理功能时,请参阅本页。
+
+虚拟硬件不变:启动链、内核、SEP 和设备树仍来自 PCC cloudOS IPSW(`vresearch101ap` / `vphone600ap`)。只有用户空间改为来自 iPad 的恢复 IPSW,而非 iPhone17,3 的;设备树也会被改写,让用户空间认为自己运行在 iPad 上。
+
+![在 vphone 虚拟机中运行的 iPadOS 主屏幕](../../ipados-demo.jpeg)
+
+## 创建 iPad 客户机
+
+### 在 Launchpad 中
+
+1. 选择 **New Machine**(新建虚拟机)。
+2. 在 **Device**(设备)下选择 iPad,在 **iPadOS** 下选择版本。推荐的 cloudOS 会一并选好。
+3. 如果 IPSW 不在目录中,请把 **Source**(来源)设为 **Custom IPSWs**(自定义 IPSW),把 iPad IPSW 填入 **iPhone IPSW** 栏,把 cloudOS IPSW 填入另一栏。
+
+只有当 Core Bundle 的目录中列出了 iPad 时,才会出现 **Device** 菜单。在终端中,`vphone-launchpad-cli vm create <name> --device iPad16,1` 可以完成同样的操作。
+
+### 使用 vphone-cli
+
+在原本填 iPhone 恢复 IPSW 的地方传入 iPad 的恢复 IPSW。cloudOS 与同版本的 iPhone 客户机所用的相同。
+
+```sh
+vphone-cli vm create ipad-mini \
+ --iphone-source 'https://updates.cdn-apple.com/2026SummerFCS/cf7db64d-5866-4bf2-bfff-50a32f58bec3/iPad16,1,iPad16,2_26.6.2_23G90_Restore.ipsw' \
+ --cloudos-source 'https://updates.cdn-apple.com/private-cloud-compute/c0ecdb4b310cf5239ab2b248dd3098eec297dc5aa3bbe6ada27273262b0b8b64'
+
+# The 13-inch iPad Pro (M5), from the IPSW that also carries the 11-inch
+vphone-cli vm create ipad-pro-13 --device iPad17,3 \
+ --iphone-source 'https://updates.cdn-apple.com/2026SummerFCS/<…>/iPad17,1,iPad17,2,iPad17,3,iPad17,4_26.6.2_23G90_Restore.ipsw' \
+ --cloudos-source 'https://updates.cdn-apple.com/private-cloud-compute/c0ecdb4b310cf5239ab2b248dd3098eec297dc5aa3bbe6ada27273262b0b8b64'
+```
+
+查找版本:
+
+| 命令 | 列出的内容 |
+| --- | --- |
+| `vphone-cli fw catalog` | 每款受支持 iPad 的 iPadOS 版本,以及各自对应的 cloudOS |
+| `vphone-cli fw catalog --device iPad16,1` | 一款 iPad 的版本 |
+| `vphone-cli fw prepare --device iPad16,1 --list` | 该 iPad 可下载的 IPSW |
+| `vphone-cli fw prepare --device iPad16,1 --iphone-version 26.6.2` | 解析出一个 IPSW |
+
+指定 `--device` 但不提供来源时,`vm create` 会列出该 iPad 的版本供你选择。
+
+### 在共用的 IPSW 中选择机型
+
+大多数 iPad IPSW 覆盖多个机型;iPad Air 和 iPad Pro 的 IPSW 同时包含两种尺寸。不指定 `--device` 时,`fw prepare` 会使用 IPSW 列出的第一个机型(11 英寸)。要使用 13 英寸机型,请给 `fw prepare` 或 `vm create` 传入 `--device iPad17,3`。Launchpad 的 New Machine 会传入在 **Device** 下选择的机型;选择 **Custom IPSWs** 时则使用第一个机型。
+
+<img src="../../ipados/ipad-pro-13-home.jpg" alt="在 vphone 虚拟机中运行的 13 英寸 iPad Pro 主屏幕" width="360" />
+
+### 手动运行各个阶段
+
+手动阶段与 iPhone 客户机相同:`vm new`、`fw prepare`、`fw patch`、DFU 和 `restore`、`cfw install`、`vm launch`。对 iPad 而言,只有 `fw prepare` 和 `fw patch` 的行为不同;DFU、`restore` 和 `cfw install` 照常运行。
+
+## 支持的设备
+
+| 产品 | 机型 | 主板 | 面板 | 点数 @2x |
+| --- | --- | --- | --- | --- |
+| `iPad16,1` | iPad mini (A17 Pro) | J410AP | 1488x2266 @ 326 ppi | 744x1133 |
+| `iPad15,7` | iPad (A16) | J481AP | 1640x2360 @ 264 ppi | 820x1180 |
+| `iPad15,3` | iPad Air 11 英寸 (M3) | J607AP | 1640x2360 @ 264 ppi | 820x1180 |
+| `iPad15,5` | iPad Air 13 英寸 (M3) | J637AP | 2048x2732 @ 264 ppi | 1024x1366 |
+| `iPad16,3` | iPad Pro 11 英寸 (M4) | J717AP | 1668x2420 @ 264 ppi | 834x1210 |
+| `iPad16,5` | iPad Pro 13 英寸 (M4) | J720AP | 2064x2752 @ 264 ppi | 1032x1376 |
+| `iPad17,1` | iPad Pro 11 英寸 (M5) | J817AP | 1668x2420 @ 264 ppi | 834x1210 |
+| `iPad17,3` | iPad Pro 13 英寸 (M5) | J820AP | 2064x2752 @ 264 ppi | 1032x1376 |
+
+蜂窝网络机型(`iPad16,2`、`iPad15,4`、`iPad15,6`、`iPad16,4`、`iPad16,6`、`iPad17,2`、`iPad17,4`)与对应的无线局域网机型共用 IPSW,并以该机型运行:虚拟机没有基带。`iPad15,8` 使用单独的 IPSW,其中不含无线局域网机型的主板,因此不受支持。
+
+已测试的组合见[兼容性](compatibility.md)。
+
+## iPad 有哪些不同
+
+- **`fw prepare`** 根据 `SupportedProductTypes` 识别 IPSW,为客户机的主板选取对应的抹掉身份和 `DeviceMap` 条目(一个 iPad IPSW 覆盖多款主板),并把产品类型和 iPad 的显示参数记录到虚拟机的 `config.plist` 中(`guestProductType`、`screenConfig`)。恢复目录命名为 `iPhoneOS_iPad16,1_<version>_<build>_Restore`;`iPhone` 前缀是所有读取方都依赖的恢复目录命名约定,与设备无关。
+- **两份设备树。** 混合清单通常让 `DeviceTree` 和 `RestoreDeviceTree` 指向同一个 vphone600 文件。对 iPad,`DeviceTree` 指向一份副本 `Firmware/all_flash/DeviceTree.vphone600ap.guest.im4p`。恢复时启动的是未修改的身份,`restored_external` 会将其与清单(`iPhone99,11`)核对;客户机启动的则是副本。
+- **`fw patch`** 为这份副本赋予 iPad 的身份和呈现方式(补丁集 `devicetree`,条目 `devicetree-cfw-ipad_*`):
+ - 根节点的 `model`、`target-type` 和 `target-sub-type` 与主板一致(iPad mini 为 `iPad16,1`、`J410`、`J410AP`),`compatible` 把主板放在第一位,`VPHONE600AP` 保留在第二位;
+ - `/product`:主板的图稿风格(idiom)、子类型和缩放比例、产品名称、外观、摄像头和按键布局、多任务处理能力(`medusa-overlay-app-capability`、`ui-floating-live-app`、`ui-overlay-app`、`ui-pinned-app`,以及在没有台前调度的主板上设置 `disable-chamois`),还有产品类型和唯一机型,全部读取自恢复目录中保留的主板 `DeviceTree.<board>.im4p`;
+ - 移除仅适用于手机的 `syscfg` 占位项(灵动岛、便捷访问、响铃开关、音量按钮布局、CarPlay、Apple Watch 配对)。
+
+ 虚拟硬件保留 vphone600 的描述:GPU 功能集、帧缓冲区、内存等级和启动标志。
+- **LLB** 在 iPad 客户机上多一个补丁 `llb-cfw-display_scale`。LLB 会根据半虚拟化显示器的启动视频字填写 `/chosen/display-scale`,而该值始终表示 3x;MobileGestalt 会把这个属性转换为屏幕缩放比例,因此 iPad 会得到一块 496x755 点的画布。该补丁让 LLB 写入 iPad 自己的缩放比例(2x,iPad mini 为 744x1133 点)。
+- **`cfw install`** 不改动已安装的设备树。iPad 客户机会跳过 iPhone17,3 恢复后的身份改写(`preboot-exp-devicetree_identity`)。
+- **虚拟机窗口**遵循 `screenConfig`,因此会按 iPad 的宽高比打开。
+
+<img src="../../ipados/display-scale-3x-before.jpg" alt="打 LLB 补丁之前,以 3x 显示缩放比例运行的 iPad 客户机" width="240" />
+
+## 添加其他 iPad
+
+添加一款 iPad 机型只需在 [`VPhoneGuestDevice`](../../../VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneGuestDevice.swift) 中加一行:它的产品类型、主板和面板。设备树需要的其他内容都读取自 IPSW 中该主板自己的 `DeviceTree.<board>.im4p`。
+
+## 另请参阅
+
+- [其他 iPhone 机型](iphone-models.md)
+- [固件兼容性](compatibility.md)
+- [创建与运行虚拟机](../machines/create-and-run.md)
diff --git a/Documents/zh/firmware/iphone-models.md b/Documents/zh/firmware/iphone-models.md
new file mode 100644
index 00000000..962bb9cc
--- /dev/null
+++ b/Documents/zh/firmware/iphone-models.md
@@ -0,0 +1,67 @@
+# 其他 iPhone 机型
+
+如何运行一个 iOS 来自其他 iPhone 恢复 IPSW、而非 iPhone17,3(iPhone 16)的客户机。需要特定机型的用户空间、面板尺寸或身份时,请参阅本页。
+
+与 [iPad 客户机](ipados.md)一样,虚拟硬件保持不变:启动链、内核、SEP 和设备树仍来自 PCC cloudOS IPSW(`vresearch101ap` / `vphone600ap`)。只有用户空间来自所选机型的 IPSW,客户机启动所用的设备树也会被改写,以呈现为该机型。
+
+## 创建
+
+在 Launchpad 中,选择 **New Machine**(新建虚拟机),在 **Device**(设备)下选择机型,在 **iOS** 下选择版本。
+
+在终端中通过 Launchpad 创建:
+
+```sh
+vphone-launchpad-cli vm create iphone17pro --device iPhone18,1
+```
+
+使用 `vphone-cli` 时,传入该机型的 IPSW 和 cloudOS:
+
+```sh
+vphone-cli vm create iphone17pro \
+ --iphone-source 'https://updates.cdn-apple.com/2026SummerFCS/f768ecdf-e037-44e6-bfa6-949b6d127c4f/iPhone18,1_26.6.2_23G90_Restore.ipsw' \
+ --cloudos-source 'https://updates.cdn-apple.com/private-cloud-compute/c0ecdb4b310cf5239ab2b248dd3098eec297dc5aa3bbe6ada27273262b0b8b64'
+```
+
+每款 iPhone 都有自己的 IPSW,因此明确指定来源时不需要 `--device`。
+
+要查找版本,请运行 `fw catalog`。它会列出 iPhone 16 和 iPhone 17 系列机型从 26.0 到 27.0.1 的版本(iPhone 17e 从 26.3.1 起),以及 iPhone 18 Pro 的 27.0.1,每个版本都附有同版本 iPhone17,3 所用的 cloudOS。只列出一款机型的版本:
+
+```sh
+vphone-cli fw catalog --device iPhone18,1
+```
+
+## 支持的设备
+
+| 产品 | 机型 | 主板 | 面板 | 点数 @3x |
+| --- | --- | --- | --- | --- |
+| `iPhone17,3` | iPhone 16 | D47AP | 1290x2796 @ 460 ppi | 430x932 |
+| `iPhone17,4` | iPhone 16 Plus | D48AP | 1290x2796 @ 460 ppi | 430x932 |
+| `iPhone17,1` | iPhone 16 Pro | D93AP | 1206x2622 @ 460 ppi | 402x874 |
+| `iPhone17,2` | iPhone 16 Pro Max | D94AP | 1320x2868 @ 460 ppi | 440x956 |
+| `iPhone17,5` | iPhone 16e | V59AP | 1170x2532 @ 460 ppi | 390x844 |
+| `iPhone18,3` | iPhone 17 | V57AP | 1206x2622 @ 460 ppi | 402x874 |
+| `iPhone18,4` | iPhone Air | D23AP | 1260x2736 @ 460 ppi | 420x912 |
+| `iPhone18,1` | iPhone 17 Pro | V53AP | 1206x2622 @ 460 ppi | 402x874 |
+| `iPhone18,2` | iPhone 17 Pro Max | V54AP | 1320x2868 @ 460 ppi | 440x956 |
+| `iPhone18,5` | iPhone 17e | V159AP | 1170x2532 @ 460 ppi | 390x844 |
+| `iPhone19,2` | iPhone 18 Pro | V63AP | 1206x2622 @ 460 ppi | 402x874 |
+
+每款机型(包括 iPhone17,3)的面板和身份都来自它自己的设备树;iPhone17,3 的面板就是它一直以来使用的显示参数。
+
+iPhone 17 Pro、17 Pro Max 和 18 Pro 有启动验证记录;见[兼容性](compatibility.md)。iPhone 17 Pro 和 17 Pro Max 在 iOS 27 上需要一个补丁,详见该页。
+
+> [!WARNING]
+> iPhone19,2 使用 ARM64E_X1。在不原生支持 X1 的宿主机上,standard 预设会把不支持的指令降级处理,这会削弱与 PC 绑定的指针认证。
+
+## 其他 iPhone 有哪些不同
+
+[iPad 有哪些不同](ipados.md)中列出的内容全部适用,但有两点区别:
+
+- 主板的 `/product` 值同样会替换 vphone600 的占位值,但 iPhone 主板保留手机特有的属性:灵动岛、便捷访问、OLED、音量按钮布局、CarPlay 和 Apple Watch 配对都取自主板,而不会被移除。补丁 ID 仍是 `devicetree-cfw-ipad_*`;它们是在 iPhone 使用之前命名的。
+- 不会为显示缩放比例给 LLB 打补丁。半虚拟化显示器的启动视频字表示 3x,这本来就是 iPhone 的缩放比例。
+
+## 另请参阅
+
+- [iPadOS 客户机](ipados.md)
+- [固件兼容性](compatibility.md)
+- [创建与运行虚拟机](../machines/create-and-run.md)
diff --git a/Documents/zh/get-started/downloads.md b/Documents/zh/get-started/downloads.md
new file mode 100644
index 00000000..efe333a6
--- /dev/null
+++ b/Documents/zh/get-started/downloads.md
@@ -0,0 +1,86 @@
+# 下载
+
+选择要下载的 Launchpad 版本以及与之配套的 `VPhone.bundle`。如果最新版本没有已公证的 Launchpad,或者需要手动匹配版本,请参阅本页。
+
+## 每个版本包含的文件
+
+每个[版本](https://github.com/Lakr233/vphone-cli/releases)最多包含三个文件:
+
+| 文件 | 内容 |
+| --- | --- |
+| `vphone-launchpad-<version>-notarized.zip` | Launchpad,已由 Apple 签名和公证。有这个文件时请下载它。 |
+| `vphone-launchpad-<version>.zip` | Launchpad,未经公证。首次打开时 macOS 会阻止它。 |
+| `VPhone-<version>.zip` | `VPhone.bundle`。Launchpad 会替你下载并安装,因此不需要这个文件。 |
+
+要打开未经公证的版本,先打开一次,然后前往**系统设置 > 隐私与安全性**,点击**仍要打开**。
+
+## 已公证的 Launchpad 版本
+
+| 系列 | 已公证 | 未公证 |
+| --- | --- | --- |
+| 2.15 | 2.15.0 | 2.15.1 |
+| 2.14 | 2.14.0 | 2.14.1, 2.14.2 |
+| 2.13 | 2.13.0 | 2.13.1, 2.13.2, 2.13.3, 2.13.4, 2.13.5, 2.13.6, 2.13.7, 2.13.8 |
+| 2.12 | 2.12.0, 2.12.2 | 2.12.1 |
+| 2.11 | 2.11.0 | — |
+| 2.10 | 2.10.1 | — |
+| 2.9 | 2.9.0, 2.9.1, 2.9.2 | 2.9.3, 2.9.4, 2.9.5 |
+| 2.8 | 2.8.0 | — |
+| 2.7 | 2.7.0 | — |
+| 2.6 | 2.6.0 | 2.6.1 |
+| 2.5 | 2.5.0 | 2.5.1 |
+| 2.4 | 2.4.0, 2.4.1 | 2.4.2 |
+| 2.3 | 2.3.0 | 2.3.1, 2.3.2 |
+| 2.2 | 2.2.0, 2.2.2, 2.2.3, 2.2.4, 2.2.5 | 2.2.1 |
+| 2.1 | 2.1.0, 2.1.1, 2.1.2 | 2.1.3, 2.1.4, 2.1.5, 2.1.6, 2.1.7 |
+| 2.0 | 2.0.4, 2.0.5, 2.0.6, 2.0.8, 2.0.9 | — |
+
+没有 2.0.7 和 2.10.0 版本。
+
+## 匹配 Launchpad 与 VPhone.bundle
+
+请使用与 Launchpad 同一系列的 `VPhone.bundle`。系列是版本号的前两个数字:Launchpad 2.2.3 属于 2.2 系列,可以与任何 `VPhone.bundle` 2.2.x 配合使用。
+
+| Launchpad | VPhone.bundle |
+| --- | --- |
+| 2.15.x | 2.15.x |
+| 2.14.x | 2.14.x |
+| 2.13.x | 2.13.x |
+| 2.12.x | 2.12.x |
+| 2.11.x | 2.11.x |
+| 2.10.x | 2.10.x |
+| 2.9.x | 2.9.x |
+| 2.8.x | 2.8.x |
+| 2.7.x | 2.7.x |
+| 2.6.x | 2.6.x |
+| 2.5.x | 2.5.x |
+| 2.4.x | 2.4.x |
+| 2.3.x | 2.3.x |
+| 2.2.x | 2.2.x |
+| 2.1.x | 2.1.x |
+| 2.0.x | 2.0.x |
+
+在同一系列中,请安装最新的 `VPhone.bundle`。补丁版本只修复问题,不会改变 Launchpad 与 bundle 的配合方式。
+
+Launchpad 会拒绝对它来说过旧的 `VPhone.bundle`,但仍可能列出更新系列的 bundle。不要安装这些 bundle;请先把 Launchpad 更新到该系列。
+
+> [!NOTE]
+> Launchpad 不会自动更新。请从版本页面下载新版本,替换旧的 App。
+
+## 近期系列新增的内容
+
+| 系列 | 新增 | 说明 |
+| --- | --- | --- |
+| 2.15 | HomeView | 请将 Launchpad 2.15 与同系列的 bundle 搭配使用,这样 New Machine 会为 `HomeAccessory17,1` 和 `HomeAccessory17,2` 选择 `homeview` 预设。 |
+| 2.14 | 从文件载入补丁预设:预设选择器中的 **Other…**,或 `--preset <path>` | Launchpad 2.14 需要 2.14 的 bundle。 |
+| 2.13 | Apple TV 4K(第 4 代) | 请将 Launchpad 2.13 与同系列的 bundle 搭配使用,这样 New Machine 会为 `AppleTV18,1` 选择 `tvos-4k` 预设。 |
+
+## 1.x 版本
+
+1.x 创建的虚拟机无法在 2.x 中启动。1.x 请参阅 [1.0.14 版本](https://github.com/Lakr233/vphone-cli/releases/tag/1.0.14)。
+
+## 另请参阅
+
+- [快速开始](quick-start.md)
+- [Core Bundle](../launchpad/core-bundles.md)
+- [Launchpad 命令行](../launchpad/launchpad-cli.md)
diff --git a/Documents/zh/get-started/host-setup.md b/Documents/zh/get-started/host-setup.md
new file mode 100644
index 00000000..bb6c9d4e
--- /dev/null
+++ b/Documents/zh/get-started/host-setup.md
@@ -0,0 +1,112 @@
+# 宿主机设置
+
+让 Mac 能够运行带授权的虚拟机进程 `vphone-vm`。每台 Mac 只需设置一次;每当 `vphone-vm` 的签名发生变化,都要重复允许列表这一步。
+
+你需要一台运行 macOS 15 或更新版本的 Apple Silicon Mac。PV=3 研究客户机无法在嵌套的 macOS 虚拟机中运行。
+
+## 检查宿主机
+
+使用你所用 `VPhone.bundle` 中的程序运行预检:
+
+```sh
+vphone-cli host preflight
+```
+
+它会在任何虚拟机启动前检查带授权的 `vphone-vm`。如果 AMFI 拒绝 `vphone-vm`,错误信息会打印出针对该 bundle 的完整命令 `sudo .../vphone-escalator allow .../vphone-vm`。
+
+## 选择安全配置
+
+`vphone-vm` 带有 Apple 私有的虚拟化授权,因此 macOS 必须接受它。下面两种方式都需要在恢复环境中启用 Research Guests(研究客户机)。二选一即可。
+
+### 方式 A:保持 SIP 启用,放宽调试限制
+
+1. 启动进入 macOS 恢复,打开终端,运行:
+
+ ```sh
+ csrutil enable --without debug
+ csrutil allow-research-guests enable
+ ```
+
+2. 重新启动进入 macOS。
+3. 把当前的 `vphone-vm` 加入允许列表。使用发布版 bundle 时,运行 `vphone-cli host preflight`,再运行它打印出的命令。使用源码检出时:
+
+ ```sh
+ bundle=.build/XcodeBundle/Build/Products/Debug/VPhone.bundle
+ sudo "$bundle/Contents/MacOS/vphone-escalator" allow "$bundle/Contents/MacOS/vphone-vm"
+ "$bundle/Contents/MacOS/vphone-escalator" status
+ "$bundle/Contents/MacOS/vphone-cli" host preflight
+ ```
+
+> [!WARNING]
+> 每次构建后都要重新运行 `allow` 命令,包括只改变了签名的重新构建。允许列表记录的是 `vphone-vm` 的 cdhash,新的签名会产生新的 cdhash。
+
+撤销允许列表:
+
+```sh
+sudo "$bundle/Contents/MacOS/vphone-escalator" off
+```
+
+`off` 只移除 `vphone-escalator` 添加的哈希,并重启 amfid。偏好设置及其中的其他值会保留。
+
+如果其他已签名的宿主机程序需要受限授权,也可以把它们一并传给同一条 `allow` 命令。不带授权的 `vphone-cli` 不需要这样做。
+
+### 方式 B:停用 SIP 和 AMFI
+
+这是限制更宽松的配置。
+
+1. 启动进入 macOS 恢复,打开终端,运行:
+
+ ```sh
+ csrutil disable
+ csrutil allow-research-guests enable
+ ```
+
+2. 重新启动进入 macOS,设置启动参数,然后再次重新启动:
+
+ ```sh
+ sudo nvram boot-args="amfi_get_out_of_my_way=1 -v"
+ ```
+
+> [!WARNING]
+> 这会覆盖现有的 `boot-args`。请先用 `nvram boot-args` 查看。
+
+## 使用 Launchpad 时
+
+Launchpad 的 bundle 预检会确认 SIP 调试限制已停用(或 SIP 已完全停用),并且 Research Guests 已启用。你不需要自己运行 `vphone-escalator`:
+
+- 如果 AMFI 阻止已安装的 `vphone-vm`,Launchpad 的辅助程序会再次检查这些宿主机设置,验证 root 拥有的 bundle 及其记录的 cdhash,以 root 身份运行该 bundle 的 `vphone-escalator allow`,然后 Launchpad 重新预检。
+- 每个新的 bundle 签名都会单独检查和允许。
+- 当新版 Launchpad 带有新版辅助程序时,它会在启动时请求管理员授权以更新辅助程序。
+
+独立使用的 `vphone-cli` 仍会报告需要手动运行的命令。
+
+## 从源码构建
+
+发布版 `VPhone.bundle` 在运行时不需要 Homebrew、Python 或 Xcode。从源码构建需要 Xcode 及其 iPhoneOS SDK,用于编译 `vphoned`。在源码目录中运行:
+
+```sh
+xcodebuild -workspace VPhone.xcworkspace -scheme VPhone \
+ -configuration Debug -destination 'platform=macOS,arch=arm64' \
+ -derivedDataPath .build/XcodeBundle build
+.build/XcodeBundle/Build/Products/Debug/VPhone.bundle/Contents/MacOS/vphone-cli host preflight
+```
+
+`VPhone` scheme 会生成包含全部程序的 ad hoc 签名 bundle。使用方式 A 时,每次新构建都要加入允许列表。
+
+## 允许列表改动了什么
+
+`vphone-escalator allow` 会在 AMFI 代码要求偏好设置不存在时创建它。如果已经存在,就把当前 `vphone-vm` 的 cdhash 追加到其中的 `Entitlements` 要求里,保留其他 cdhash 和偏好设置键,并跳过已有的哈希。它不改动现有的 `AllowUnsafeDynamicLinking` 值,只在该键不存在时写入 `false`。它通过修改 amfid 堆中的一个字节,让 amfid 参考这项要求。
+
+## bundle 包含的内容
+
+- `vphone-cli` 在没有私有授权的情况下协调各项工作,并通过 `vphone-cli archive` 处理归档。
+- `vphone-vm` 是已签名、带授权的虚拟机和窗口进程。
+- `vphoned` 在构建时为 iOS 编译,并安装到每个新建的客户机中。
+
+实现历史见[关于程序拆分的研究记录](../../../Research/Host/host_binary_split.md)。
+
+## 另请参阅
+
+- [快速开始](quick-start.md)
+- [创建与运行虚拟机](../machines/create-and-run.md)
+- [故障排查](../help/troubleshooting.md)
diff --git a/Documents/zh/get-started/overview.md b/Documents/zh/get-started/overview.md
new file mode 100644
index 00000000..9c318436
--- /dev/null
+++ b/Documents/zh/get-started/overview.md
@@ -0,0 +1,50 @@
+# 概览
+
+vphone-cli 在 Apple Silicon Mac 上运行虚拟 iPhone。本页介绍它能做什么、Mac 需要满足哪些条件,以及各个程序分别负责什么。
+
+> [!WARNING]
+> 本项目从未发行或授权发行任何虚拟货币或代币,也不接受任何虚拟货币付款或捐赠。任何以本项目名义发行、推广或声称与本项目有关的虚拟货币或代币,均属诈骗。
+
+![在 macOS 上运行的虚拟 iPhone](../../demo.jpeg)
+
+vphone-cli 使用 Apple 的 Virtualization.framework 和 PCC 研究虚拟机运行 iOS,适用于安全研究、逆向工程和调试。
+
+## 功能
+
+- **图形窗口**:在 Mac 上操作虚拟 iPhone 的屏幕,浏览 App 和文件,截屏和录屏。
+- **自定义固件**:系统已预先打好补丁,可以安装[软件包环境](../machines/package-environment.md)。
+- **备份与克隆**:导出、导入和克隆虚拟机。
+- **自动化 API**:可选的本机 HTTP 和 WebSocket 接口。见[自动化 API](../machines/automation-api.md)。
+- **无需额外依赖**:运行时不需要 Xcode、Python 或 Homebrew。
+
+## 系统要求
+
+- 一台实体 Apple Silicon Mac,运行 macOS 15 或更新版本。无法在 macOS 虚拟机中使用。
+- 足够的磁盘空间。每台虚拟机默认使用 64 GB 虚拟磁盘,固件另外占用空间。
+- 网络连接。恢复系统时需要在线获取签名票据。
+- 调整安全设置。启动进入 macOS 恢复,在终端中运行以下命令,然后重新启动:
+
+ ```sh
+ csrutil enable --without debug
+ csrutil allow-research-guests enable
+ ```
+
+ SIP 仍保持启用,只放宽调试限制。详情见[宿主机设置](host-setup.md)。
+
+## 四个程序
+
+| 程序 | 作用 |
+| --- | --- |
+| `vphone-launchpad` | Mac App,负责下载和安装 `VPhone.bundle`,并配置宿主机。单独发布。 |
+| `vphone-cli` | 准备固件、打补丁、恢复系统、管理虚拟机。 |
+| `vphone-vm` | 运行虚拟机并显示虚拟机窗口。 |
+| `vphoned` | 虚拟机中的控制服务。窗口中的功能和 API 都通过它实现。 |
+
+`vphone-cli`、`vphone-vm` 和 `vphoned` 一起包含在 `VPhone.bundle` 中。Launchpad 通过该 bundle 中的 `vphone-cli` 管理每台虚拟机;你也可以在终端中直接运行 `vphone-cli`。
+
+## 另请参阅
+
+- [快速开始](quick-start.md)
+- [宿主机设置](host-setup.md)
+- [下载](downloads.md)
+- [创建与运行虚拟机](../machines/create-and-run.md)
diff --git a/Documents/zh/get-started/quick-start.md b/Documents/zh/get-started/quick-start.md
new file mode 100644
index 00000000..0c346f9a
--- /dev/null
+++ b/Documents/zh/get-started/quick-start.md
@@ -0,0 +1,40 @@
+# 快速开始
+
+用 Launchpad 设置 vphone,并启动第一台虚拟 iPhone。请在 Mac 满足[系统要求](overview.md)后再进行。
+
+## 用 Launchpad 设置
+
+1. 从[最新版本](https://github.com/Lakr233/vphone-cli/releases/latest)下载 `vphone-launchpad-<version>-notarized.zip`,解压并打开。并非每个版本都经过公证。如果最新版本没有 `-notarized` 文件,请在[下载](downloads.md)中选择一个已公证的版本。
+2. 在 **Host Setup**(宿主机设置)中授予开发者工具权限,并安装辅助程序。
+3. 在 **Core Bundle** 中点击 **Download and Install**(下载并安装)。
+4. 在 **Machines**(虚拟机)中点击 **New Machine**(新建虚拟机),选择固件组合,然后点击 **Create**(创建)。
+
+Launchpad 会下载固件、打补丁、恢复系统并启动虚拟机。要使用自己的 iPhone 和 cloudOS IPSW,请参阅[兼容性](../firmware/compatibility.md)。
+
+## 让 Agent 代劳
+
+如果你在这台 Mac 上使用编程 Agent(Claude Code、Codex 等),可以直接粘贴下面的提示词,不必手动操作。Agent 会读取 vphone skill,检查哪些已经设置好,安装 Launchpad 和 `VPhone.bundle`;遇到需要你处理的步骤(例如输入管理员密码,或在 macOS 恢复中进行更改)时会停下来询问。
+
+```text
+在这台 Mac 上设置 vphone。先阅读这个 skill:
+https://raw.githubusercontent.com/Lakr233/vphone-cli/main/Skills/vphone-guest-control/SKILL.md
+以及它在 references/(同一目录)下链接的文件,然后照着做:
+安装最新的已公证 vphone-launchpad(并非每个 release 都有 -notarized 压缩包),
+把 vphone-launchpad-cli 加到 PATH,安装与 Launchpad 系列一致的 VPhone.bundle,
+并运行 `vphone-launchpad-cli status` 检查。不要修改 SIP、boot-args 或任何其他
+宿主机安全设置;在我确认固件和可用磁盘空间之前,不要创建虚拟机。遇到需要我
+操作的步骤,请准确告诉我该做什么,然后等待。
+```
+
+## 后续步骤
+
+- 在虚拟机中安装软件包管理器:[软件包环境](../machines/package-environment.md)。
+- 在终端中管理虚拟机,或不用 Launchpad 创建虚拟机:[创建与运行虚拟机](../machines/create-and-run.md)。
+- 通过 HTTP 和 WebSocket 编写脚本控制虚拟机:[自动化 API](../machines/automation-api.md)。
+- 遇到问题:[故障排查](../help/troubleshooting.md)。
+
+## 另请参阅
+
+- [宿主机设置](host-setup.md)
+- [下载](downloads.md)
+- [Launchpad 命令行](../launchpad/launchpad-cli.md)
diff --git a/Documents/zh/help/troubleshooting.md b/Documents/zh/help/troubleshooting.md
new file mode 100644
index 00000000..0812a829
--- /dev/null
+++ b/Documents/zh/help/troubleshooting.md
@@ -0,0 +1,52 @@
+# 故障排查
+
+找到你看到的症状或错误信息,然后按照其下方的方法处理。网络问题请参阅[网络](../networking/overview.md)。
+
+## `vphone-vm` 在虚拟机打开前被终止
+
+1. 运行宿主机预检:
+
+ ```sh
+ vphone-cli host preflight
+ ```
+
+ CLI 不带授权,因此它会继续运行,并能说明 AMFI 为何拒绝与它配套的已签名 `vphone-vm`。
+2. 如果你重新构建了 bundle,cdhash 就会改变。请按照[宿主机设置](../get-started/host-setup.md)中的说明,用 bundle 自带的辅助程序允许新的二进制文件。
+
+## `Virtualization is not available on this hardware`
+
+PV=3 客户机不能嵌套运行。请在 Apple Silicon Mac 上直接启动,而不是在另一个 macOS 虚拟机中。
+
+## `vm create` 打印了 vphoned 成功信息,但没有虚拟机在运行
+
+这是正常的。创建流程会临时以图形界面启动一次,发送一次真实的 ping,并在返回前停止这次启动。要使用虚拟机,请启动它:
+
+```sh
+vphone-cli vm launch <name>
+```
+
+## 停在“Press home to continue”
+
+点击虚拟机窗口标题栏中的主屏幕按钮。当前的 JB 流程不会安装 VNC 服务器。
+
+## App 因 `EXC_GUARD` / `GUARD_TYPE_MACH_PORT` 退出
+
+内核补丁 `kernel-boot-thread_guard_violation` 会阻止致命的 Mach 端口守卫投递。它只适用于 iOS 18 基础系统,因为在这类系统上启动需要它,所有预设都会在这类系统上开启它。其他基础系统无法选择这个补丁,因此在 26.x 基础系统上触发这个守卫的 App 仍会退出。见 [issue #291](https://github.com/Lakr233/vphone-cli/issues/291)。
+
+## 恢复或首次启动失败
+
+- 在手动流程中,让虚拟机保持在 DFU 模式,直到 `restore` 退出。
+- 确认在线票据请求能够访问 Apple。
+- 对于完整流程,请用一个**新名称**并加上 `-v` 重新运行 `vm create`,以获取工具的详细输出。
+- 内存或磁盘紧张时,避免同时创建多台虚拟机。
+- 把 iPhone IPSW 与 PCC 映像组合使用之前,请查看[固件兼容性](../firmware/compatibility.md)。
+
+## 客户机已启动,但 vphoned 在创建期间没有响应
+
+首次启动检查会在 300 秒后超时。创建流程使用图形界面启动,因为新恢复的客户机在首次无界面启动时可能不会启动 vphoned。成功标记能证明什么,请参阅[创建与运行](../machines/create-and-run.md)。
+
+## 另请参阅
+
+- [宿主机设置](../get-started/host-setup.md)
+- [创建与运行](../machines/create-and-run.md)
+- [固件兼容性](../firmware/compatibility.md)
diff --git a/Documents/zh/launchpad/bundle-integration.md b/Documents/zh/launchpad/bundle-integration.md
new file mode 100644
index 00000000..9f7add0d
--- /dev/null
+++ b/Documents/zh/launchpad/bundle-integration.md
@@ -0,0 +1,59 @@
+# VPhone bundle 集成
+
+如果你开发的应用程序需要分发或驱动 `VPhone.bundle`(就像 `vphone-launchpad` 那样),请阅读本页。本页介绍 bundle 包含哪些内容,以及集成它的应用程序需要负责哪些工作。
+
+## 构建与验证
+
+```sh
+xcodebuild -workspace VPhone.xcworkspace -scheme VPhone \
+ -configuration Debug -destination 'platform=macOS,arch=arm64' \
+ -derivedDataPath .build/XcodeBundle build
+```
+
+`VPhone` scheme 会生成 `VPhone.bundle`,`ValidateBundle.sh` 会在构建过程中检查它。
+
+## 如何集成
+
+- 保持 bundle 完整,以进程方式启动 `Contents/MacOS/vphone-cli`。bundle 是可执行文件和资源的容器,不是 macOS App,也不是动态载入的插件。CLI 通过解析自己的可执行文件路径来找到与它配套的 `vphone-vm`。
+- 把整个 bundle 作为一个带版本的单元来安装和更新。不要原地改写已签名的二进制文件。
+- `vphone-vm` 改变时,它的 cdhash 也会改变。启动新构建之前,请先为它安排 AMFI 准入。
+- 下载、版本验证、宿主机授权、安装和更新策略都由你的应用程序负责。开发者工具权限和 AMFI 授权是宿主机上两项独立的决定。
+- 虚拟机资料库和缓存位于 `VPhone.bundle` 之外,默认在 `~/.vphone` 下。宿主机上的虚拟机输出使用 `0777` 权限,以便独立的工作站进程访问,包括以 root 身份创建之后。`Disk.img` 内客户机文件系统的权限保持其自身的语义。
+
+## bundle 内容
+
+| 路径 | 作用 |
+| --- | --- |
+| `Contents/MacOS/vphone-cli` | 不带授权的命令入口 |
+| `Contents/MacOS/vphone-vm` | 虚拟机和窗口进程;带有私有虚拟化授权 |
+| `Contents/MacOS/vphone-escalator` | 针对当前虚拟机 cdhash 的 AMFI 允许列表工具 |
+| `Contents/MacOS/libswiftCompatibilitySpan.vphone.dylib` | `vphone-vm` 在 macOS 15 上使用的 Swift 向后部署库 |
+| `Contents/Resources/guest-resources/vphoned` | 预先签名、带有自己授权的客户机守护进程;bundle 中没有未签名的副本 |
+| `Contents/Resources/guest-resources/*.dylib` | 客户机库:launchd hook、SystemHook、相机 hook、GPU 编译器插件,以及 [`VPhoneGuestComponents`](../../../VPhoneGuestComponents/README.md) 中列出的修复和设备适配 |
+| `Contents/Resources/guest-resources/*.plist` | 客户机启动守护进程配置、相机 hook 和 MISFix 过滤规则 |
+| `Contents/Resources` | 本地化字符串;不附带签名脚本或授权文件 |
+
+`Contents/MacOS` 只包含在 Mac 上运行的程序。`guest-resources` 只包含安装到客户机中的文件,其中每个 Mach-O 都是为 iOS 构建的。`ValidateBundle.sh` 会强制执行这两条规则。
+
+## 签名
+
+所有可执行内容都使用 ad hoc 代码签名。只有需要私有授权的子进程才带有私有授权。bundle 没有 `CFBundleExecutable`、App 启动器、SMJobBless 辅助程序、安装器、密码提示,也不会自动获取 root 权限。
+
+## 隐私权限
+
+macOS 会代表负责进程请求隐私权限(麦克风、定位),并把授权与该进程的代码签名绑定。
+
+- 如果你在放弃责任的情况下启动 `vphone-cli`,它就会成为 `vphone-vm` 的负责进程。它是 ad hoc 签名的,因此每个新的 bundle 构建都会再次请求权限。
+- 如果你把 `vphone-cli` 作为签名稳定的进程的普通子进程启动,且不放弃责任,权限只会请求一次。
+
+Launchpad 采用第二种方式,使用它自己 `Contents/MacOS` 中的 `vphone-launchpad-launcher`。macOS 会把那里的工具归属到外层 App,因此提示、用途说明和授权都属于该 App。在强化运行时下,App 的主可执行文件必须带有对应的资源授权(`com.apple.security.device.audio-input`、`com.apple.security.personal-information.location`);否则 macOS 会直接拒绝请求,不会询问用户。
+
+## 版本兼容性
+
+Launchpad 会拒绝早于 `minimumBundleComponents`(在 [`VPhoneLaunchpad/VPhoneLaunchpadShared/VPhoneLaunchpadBundleStore.swift`](../../../VPhoneLaunchpad/VPhoneLaunchpadShared/VPhoneLaunchpadBundleStore.swift) 中设置)的 bundle,也不会载入旧的 bundle 布局。bundle 2.1.0 加入了补丁预设(`fw patches`、`fw set-patches`、`fw patch --preset`)和 `vphone-escalator` 可执行文件。
+
+## 另请参阅
+
+- [Core Bundle 与本地构建](core-bundles.md)
+- [Launchpad 命令行](launchpad-cli.md)
+- [宿主机设置](../get-started/host-setup.md)
diff --git a/Documents/zh/launchpad/core-bundles.md b/Documents/zh/launchpad/core-bundles.md
new file mode 100644
index 00000000..39ab42f1
--- /dev/null
+++ b/Documents/zh/launchpad/core-bundles.md
@@ -0,0 +1,104 @@
+# Core Bundle 与本地构建
+
+每台 Launchpad 虚拟机都使用一个已安装的 `VPhone.bundle` 版本运行,即它的 Core Bundle。本页介绍如何安装本地构建、把虚拟机迁移到该构建,以及如何并排比较两个构建。
+
+## 测试 VPhone.bundle 构建
+
+1. 在仓库根目录构建 bundle:
+
+ ```sh
+ xcodebuild -workspace VPhone.xcworkspace -scheme VPhone \
+ -configuration Debug -destination 'platform=macOS,arch=arm64' \
+ -derivedDataPath .build/XcodeBundle build
+ ```
+
+2. 安装。它会以 `<version>-local.<hash>` 安装并成为默认版本,获得执行策略例外,新的 `vphone-vm` cdhash 会被允许,然后运行宿主机预检:
+
+ ```sh
+ vphone-launchpad-cli bundle install-local .build/XcodeBundle/Build/Products/Debug/VPhone.bundle
+ ```
+
+ 确切的版本号见安装结果和 `bundle list`。
+
+3. 把现有虚拟机迁移到该版本。`--update-environment` 还会重新部署新的 vphoned 和 hook dylib,并要求虚拟机处于停止状态:
+
+ ```sh
+ vphone-launchpad-cli vm set-bundle research-01 2.4.0-local.1a2b3c4d --update-environment
+ ```
+
+4. 启动虚拟机并检查:
+
+ ```sh
+ vphone-launchpad-cli vm start research-01 --wait
+ vphone-launchpad-cli guest rpc research-01 device.info
+ vphone-launchpad-cli guest rpc research-01 apps.list '{}'
+ vphone-launchpad-cli vm log research-01 --lines 100
+ vphone-launchpad-cli vm stop research-01
+ ```
+
+辅助程序的授权有效期为五分钟。授权过期后,第一个需要辅助程序的步骤会像窗口中一样,在 Mac 上要求输入管理员密码。
+
+要为现有虚拟机进行一次性的内核和客户机更新以启用持久着色器缓存,请参阅[持久着色器缓存](../storage/shader-cache.md)。
+
+## 比较两个构建
+
+安装两个构建但不改变默认版本,然后分别为它们创建虚拟机:
+
+```sh
+vphone-launchpad-cli bundle install-local /path/to/A/VPhone.bundle --keep-default
+vphone-launchpad-cli bundle install-local /path/to/B/VPhone.bundle --keep-default
+vphone-launchpad-cli bundle list # note both versions
+
+vphone-launchpad-cli vm create cmp-a --bundle 2.4.0-local.aaaaaaaa
+vphone-launchpad-cli vm create cmp-b --bundle 2.4.0-local.bbbbbbbb
+```
+
+这样创建的虚拟机在全部三层上都不同(见下文)。如果只想在同一条启动链上比较宿主机程序和客户机环境,请在窗口中克隆一台虚拟机,然后重新绑定副本:
+
+```sh
+vphone-launchpad-cli vm set-bundle cmp-b 2.4.0-local.bbbbbbbb --update-environment
+```
+
+`vm list` 会显示每一层来自哪个 bundle。有虚拟机绑定到某个版本时,`bundle remove` 会拒绝删除该版本;请先重新绑定或删除这些虚拟机。
+
+## 虚拟机如何绑定到 bundle
+
+每台虚拟机都绑定到一个已安装的版本,在创建时选定,并保存在虚拟机文件夹的 `launchpad.json` 中。安装 bundle 永远不会改变虚拟机的绑定。
+
+一台虚拟机由三层组成,每一层在不同时间取自 bundle:
+
+| 层 | 内容 | 来源 |
+| --- | --- | --- |
+| Host Programs(宿主机程序) | `vphone-cli`、`vphone-vm` | 每条命令都取自绑定的 bundle。新的绑定在下次启动时生效。 |
+| Guest Environment(客户机环境) | vphoned 和 hook dylib | 创建时由 `cfw install` 安装,之后由 `cfw update-environment`(虚拟机须停止)更新。 |
+| Boot Chain(启动链) | 打过补丁的固件、恢复、CFW 补丁 | 创建时由 `fw patch`、`restore` 和 `cfw install` 生成。 |
+
+### 之后更改启动链补丁
+
+`vphone-cli fw set-patches` 更改补丁选择,`vphone-cli fw patches <vm>` 列出尚未应用到客户机的补丁。Launchpad 会在检查器中显示数量。每类补丁应用到客户机的方式不同:
+
+| 补丁 | 应用方式 |
+| --- | --- |
+| 客户机补丁 | 下一次 `cfw update-environment` |
+| AVPBooter | 下一次 `fw patch` |
+| 内核补丁 | `cfw update-kernel`(保留数据,不需要恢复目录) |
+| 启动链的其余部分(TXM、DeviceTree、LLB) | 只能重新恢复,这会抹掉客户机 |
+
+## 默认 bundle
+
+**默认** bundle(以前称为“active”)只决定:
+
+- 未指定 `--bundle` 时,`vm create` 绑定哪个版本;
+- `exec` 和作用于整个资料库的命令使用哪个版本运行。
+
+新安装的版本会成为默认版本,除非传入 `--keep-default`。在一个 Launchpad 会话中首次启动某台虚拟机时,会检查一次它的 bundle(执行策略例外、AMFI、宿主机预检)。
+
+## 版本名称
+
+本地构建以 `<version>-local.<hash>` 安装,哈希取自 bundle 的代码签名封印,因此同一版本的两个构建可以并存。较旧的存储中可能仍有 `<version>-local` 或 `<version>-ci.<commit>`。
+
+## 另请参阅
+
+- [Launchpad 命令行](launchpad-cli.md)
+- [Bundle 集成](bundle-integration.md)
+- [下载](../get-started/downloads.md)
diff --git a/Documents/zh/launchpad/launchpad-cli.md b/Documents/zh/launchpad/launchpad-cli.md
new file mode 100644
index 00000000..1ba16e93
--- /dev/null
+++ b/Documents/zh/launchpad/launchpad-cli.md
@@ -0,0 +1,180 @@
+# Launchpad 命令行
+
+`vphone-launchpad-cli` 可以在终端或脚本中操作正在运行的 Launchpad:安装 bundle,创建、启动和停止虚拟机,以及与客户机通信。想要使用 Launchpad 的功能、又不想在窗口中逐项点击时,请使用它。
+
+## 设置
+
+CLI 位于 `vphone-launchpad.app/Contents/MacOS` 中。把它链接到你的 `PATH`:
+
+```sh
+ln -s /Applications/vphone-launchpad.app/Contents/MacOS/vphone-launchpad-cli /usr/local/bin/
+vphone-launchpad-cli help
+```
+
+Launchpad 未运行时,CLI 会启动它。由 CLI 启动的 Launchpad 会隐藏打开,不会抢走前台 App 的焦点;点击它的程序坞图标,或菜单栏中的 Open Launchpad,即可显示窗口。如果想让它启动时窗口位于前台,请传入 `--foreground`(放在命令之前,或放在除 `exec` 以外任何命令的选项中)。两种方式都不会影响已经在运行的 Launchpad。
+
+## 输出与退出状态
+
+- 进度信息实时输出到 stderr。
+- 结果是 stdout 上的一个 JSON 文档。
+- 成功时退出状态为 0,失败时为 1,原因输出到 stderr。
+- 中断 CLI 会取消可以取消的命令(`exec`、等待、CFW 安装)。bundle 安装和虚拟机创建属于窗口,会继续运行。
+
+每条命令也会显示在 Launchpad 的窗口和命令历史中。
+
+## 命令
+
+如果两个资料库中有同名虚拟机,虚拟机命令可以用 `--root <library>` 指定资料库。
+
+### 状态与 bundle
+
+| 命令 | 作用 |
+| --- | --- |
+| `status` | 宿主机检查、辅助程序、默认 bundle、虚拟机数量 |
+| `bundle list` | 已安装的版本、回执、cdhash、检查结果、绑定的虚拟机 |
+| `bundle install-local <path> [--keep-default]` | 安装本地的 `VPhone.bundle` 文件夹或 `.zip` |
+| `bundle install-release <version\|latest> [--keep-default]` | 下载并安装 GitHub release |
+| `bundle set-default <version>` | 把某个版本设为默认。`bundle use` 是旧名称 |
+| `bundle verify <version>` | 重新检查某个版本 |
+| `bundle accept <version> [--off]` | 跳过未通过的检查,或用 `--off` 停止跳过 |
+| `bundle remove <version>` | 删除没有虚拟机绑定的版本 |
+
+要安装本地构建、把虚拟机迁移到该构建,或比较两个构建,请参阅 [Core Bundle 与本地构建](core-bundles.md)。
+
+### 虚拟机
+
+| 命令 | 作用 |
+| --- | --- |
+| `vm list` | 所有资料库中的虚拟机,包括运行状态、Core Bundle 和日志路径 |
+| `vm start <name> [--headless] [--wait]` | 用虚拟机自己的 bundle 启动。`--wait` 等待 vphoned |
+| `vm stop <name>` | 请求客户机关机(vphoned `system.shutdown`),最多等待 30 秒。无法请求客户机或客户机没有停止时,直接结束虚拟机 |
+| `vm wait <name>` | 等待 vphoned |
+| `vm log <name> [--lines <n>] [--kind create\|dfu\|patch]` | 读取控制台日志 |
+| `vm create <name> [options]` | New Machine 流程;见下文“创建虚拟机” |
+| `vm set-bundle <name> <version> [--update-environment]` | 把虚拟机绑定到另一个已安装的版本 |
+| `vm leases [--release]` | 共享 NAT 网络上的 DHCP 租约及各自所属的虚拟机。`--release` 通过辅助程序释放任何资料库中都没有虚拟机使用的租约(见[旧 MAC 地址占用的地址](../networking/addresses.md)) |
+
+说明:
+
+- 在 `vm list` 中,只有持有磁盘的虚拟机进程(`vphone-vm` 或 Virtualization 的虚拟机服务)才会让虚拟机显示为 `running`。其他打开了磁盘的进程(`tail`、聚焦、备份工具)会列在 `diskOpenIn` 中(例如 `12925 tail`),虚拟机仍显示为 `stopped`。
+- 与 `vphone-cli vm launch` 一样,`vm start` 不会因为某个进程只是打开了磁盘而拒绝启动;它会打印一条提示,指出该进程。
+- `vm start --wait` 和 `vm wait` 也接受 `--timeout`。
+- `vm set-bundle --update-environment` 还会重新部署该版本的客户机环境,并要求虚拟机处于停止状态。如果有其他进程打开了磁盘,它会在更改绑定之前拒绝执行并指出该进程。如果更新本身失败,虚拟机仍会绑定到新版本,`vm list` 仍显示旧的 `guestEnvironmentBundle`;请运行 `cfw update-environment` 完成更新。
+
+### CFW
+
+这些命令在已停止的虚拟机上通过 Launchpad 的辅助程序运行,使用虚拟机自己的 bundle。如果有其他进程打开了磁盘,每条命令都会拒绝执行并指出该进程(`12925 tail`)。
+
+| 命令 | 作用 |
+| --- | --- |
+| `cfw install <name>` | 安装 CFW。适用时,辅助程序会把临时工作文件放在虚拟机资料库所在的外置宗卷上 |
+| `cfw update-environment <name>` | 重新部署 bundle 的客户机资源(vphoned、hook dylib);其他内容不变 |
+| `cfw update-kernel <name>` | 按虚拟机当前的补丁选择重新为 kernelcache 打补丁,并替换到 Preboot 中,保留数据。这是在已安装的虚拟机上更改内核补丁且保留数据的方式;不需要恢复目录 |
+
+### 客户机
+
+`guest` 命令和 `--wait` 通过虚拟机的 `vphone.sock` 通信,每次启动都会提供这个套接字。2.0.9 及更早版本的 bundle 只为带窗口启动的虚拟机提供它。
+
+| 命令 | 作用 |
+| --- | --- |
+| `guest send <name> <json>` | 发送一条原始的 `vphone.sock` 请求(tap、swipe、key、screenshot) |
+| `guest rpc <name> <method> [params]` | 调用任意 vphoned 方法;见 [`Research/vphoned_http_api.md`](../../../Research/vphoned_http_api.md)。vphoned 拒绝时,stderr 的最后一行是 JSON 格式的错误对象(`code`、`message`、`results`、`reason` …) |
+| `guest push <name> <local> <guest-path> [--mode <octal>]` | 把 Mac 上的文件拷贝到客户机。文件通过 vphoned 流式传输,因此大小不受 `guest rpc` 单行 JSON 1 MiB 的限制;适用于二进制文件和 IPA。客户机路径以 `/` 结尾时保留文件名;权限默认与 Mac 上的文件相同 |
+| `guest pull <name> <guest-path> <local>` | 把客户机中的文件流式拷贝到 Mac。`local` 可以是文件夹。文件完整传输后才会替换 `local` |
+| `guest unlock <name> [--passcode <code>] [--timeout <seconds>]` | 无论客户机处于什么状态,都点亮屏幕并解锁(vphoned `screen.unlock`)。只有客户机设置了密码时才需要 `--passcode` |
+
+### 运行 vphone-cli
+
+| 命令 | 作用 |
+| --- | --- |
+| `exec [--bundle <version>] <vphone-cli arguments>` | 运行默认 bundle 或指定版本中的 `vphone-cli`,并实时输出。`--bundle` 必须放在最前面 |
+
+## 创建虚拟机
+
+`vm create` 运行 New Machine 流程,绑定到 `--bundle <version>` 或默认 bundle。虚拟机从模板克隆,模板不存在时会先构建(2.9);使用 `--no-template` 时则单独恢复。
+
+```sh
+vphone-launchpad-cli vm create rt-e --block system-debugserver-cfw-install
+```
+
+| 选项 | 作用 |
+| --- | --- |
+| `--bundle <version>` | 把虚拟机绑定到这个已安装的版本,而不是默认版本 |
+| `--device <product-type>` | 创建其他设备;见下文“其他设备” |
+| `--preset <preset>` | 预设名称,或预设 plist 的路径(2.14),虚拟机会保留一份副本 |
+| `--block <patch>`、`--allow <patch>` | 关闭或开启预设中的某个补丁;可重复使用。见下文“补丁覆盖” |
+| `--no-template` | 单独恢复虚拟机,而不是从模板克隆 |
+| `--slim on\|off`、`--trim …`、`--keep-languages …`、`--service-profile …`、`--remove-apps …`、`--keep-apps …` | `vphone-cli vm create` 的精简开关。与 New Machine 中一样,Apple 账户随精简的服务配置一起关闭 |
+| `--accounts-off` | 可以传入,但不会改变任何设置 |
+| `--ipsw <path>` | 可选。只传给 2.12.0 bundle,它用这个文件准备 kernelcache 组合,作用与 New Machine 的 ipsw 字段相同。2.12.1 bundle 会原生提取 |
+| `--kmutil-ssh <user@host>` | 通过 ssh 链接 iOS 18 客户机(`--device iPhone11,6`)kernel-first 组合的 Mac,作用与 New Machine 的 macOS 构建机字段相同。该机上 ssh 和 sudo 的密码来自客户端的 `VPHONE_KMUTIL_SSH_PASSWORD`,绝不从参数传入 |
+| `--from <step>` | 使用创建开始时的选项,从某个步骤(`findTemplate` … `firstBoot`)重试 |
+
+解析器还接受 `--iphone-source`、`--cloudos-source`、`--cpu`、`--memory`、`--disk-size`、`--network`、`--keep-artifacts` 和 `--no-wait`;见 `vphone-launchpad-cli help`。
+
+结果会注明所用的模板、该模板是否由这次创建构建,以及所用的补丁。
+
+### 其他设备
+
+| `--device` | 客户机 | 说明 |
+| --- | --- | --- |
+| iPad 产品类型 | iPadOS | 见 [iPadOS 客户机](../firmware/ipados.md) |
+| `AppleTV5,3` | Apple TV HD | 始终单独恢复,不做精简;除非 `--preset` 指定了其他预设,否则使用 `tvos` 预设 |
+| `AppleTV14,1` | Apple TV 4K(第 3 代) | 同上,使用 `tvos-4k` 预设,用户空间来自目录中的 OTA |
+| `AppleTV18,1` | Apple TV 4K(第 4 代) | 需要 Launchpad 和 Core Bundle 2.13。选择 `tvos-4k`,单独恢复且不做精简,并使用叠加在 Apple TV HD 基础之上的完整 OTA 中的 tvOS 27.2 beta(`24K120`)。创建需要 macOS 27。实际启动测试尚未完成;见[适配记录](../../../Research/Firmware/tvos_support.md#apple-tv-4k-4th-generation) |
+
+另有两种情况会通过辅助程序以 root 身份运行某些步骤:
+
+- `--preset minimal`(Minimal:原装的启动链、内核和 TXM,在恢复前定制系统)也会单独恢复且不做精简,它的 `fw patch` 通过辅助程序以 root 身份运行。它的用户空间调试选项(`vphone-cli fw patches` 中 Features 下的 `userspace-debugging`)相当于对其列出的每个补丁使用 `--allow`。
+- 对于 cloudOS 不含 vphone600 组件的虚拟机(使用其版本自己的 cloudOS、手表、iOS 18 客户机),kernelcache 组合由 `fw kernelcache` 准备,再由辅助程序以 root 身份链接。
+
+### 补丁覆盖
+
+`--block <patch>` 和 `--allow <patch>` 接受 `vphone-cli fw patches` 列出的标识符,每个补丁用一次:
+
+```sh
+vphone-launchpad-cli exec fw patches --preset <preset>
+```
+
+Launchpad 从这次创建所用的 bundle 中读取该目录,拒绝没有任何补丁集声明的标识符以及同时被阻止和允许的标识符,并像 `fw set-patches` 一样只保留与预设不同的部分。然后它按照 New Machine 的方式把它们分为两类:
+
+- **启动链补丁**(AVPBooter、iBSS、iBEC、LLB、TXM、kernelcache、DeviceTree …)属于模板的键。Find Template 会查找带有这些补丁构建的模板,模板构建会在 `fw patch` 之前用 `fw set-patches` 记录它们。
+- **客户机补丁**不属于模板。克隆会用 `fw set-patches` 记录它们,Apply Guest Patches 步骤会在首次启动前通过辅助程序用 `cfw update-environment` 写入。因此,只有客户机覆盖设置时会复用普通模板。
+
+结果中的 `patches` 对象包含预设、`blocked` 和 `allowed` 覆盖设置,以及应用到克隆上的 `guest` 覆盖设置。使用 `--no-template` 时,所有覆盖设置都会进入虚拟机自己的恢复。`--from` 不接受 `--block` 和 `--allow`:重试会沿用这次创建的补丁。
+
+## 结果中的 bundle 字段
+
+| 命令 | 字段 | 含义 |
+| --- | --- | --- |
+| `status` | `defaultBundle` | 默认版本。`activeBundle` 为旧脚本保留相同的值 |
+| `bundle list` | `default` | 该版本是默认版本。`active` 为旧脚本保留相同的值 |
+| `bundle list` | `machines` | 绑定到该版本的虚拟机名称 |
+| `vm list` | `bundle` | 虚拟机的宿主机程序所用的版本 |
+| `vm list` | `guestEnvironmentBundle` | 最近一次安装客户机环境所用的版本;未知时为 `null` |
+| `vm list` | `bootChainBundle` | 构建启动链所用的版本;在 Launchpad 开始记录之前创建的虚拟机为 `null` |
+| `vm create`、`cfw …`、`exec` | `bundle` | 命令运行所用的版本 |
+
+当 `guestEnvironmentBundle` 与 `bundle` 不同时,宿主机和客户机来自不同的构建;运行 `cfw update-environment` 可以让客户机与之保持一致。
+
+## 触摸坐标与显示几何
+
+`guest send` 的触摸坐标以 `t:screenshot` 返回的**完整竖直截图**为准:旋转四分之一圈后,宽度和高度会互换。无论是图形界面启动还是无界面启动,宿主机都会把该点转换为固定面板的 HID 坐标。滑动会沿用开始时采样的几何信息。如果截图期间几何信息发生变化,你会收到错误,而不是一张输入坐标含义不明确的图像。
+
+要诊断旋转后坐标不匹配的问题,请读取几何信息:
+
+```sh
+vphone-launchpad-cli guest send <name> '{"t":"display.geometry"}'
+```
+
+它会返回宿主机配置的和实际捕获的像素尺寸,以及当前显示视图的边界、旋转、等比适配的绘制区域和指针/触摸路径,不会改变任何输入或显示状态。`capture_pixels` 是宿主机的原始帧;`screenshot_pixels` 和 `input_orientation` 描述输入坐标。请将其与 `device.screen`、`display.orientation` 以及客户机实际收到的事件进行比较。
+
+## 连接方式
+
+CLI 通过 `~/Library/Application Support/vphone-launchpad/control.sock` 上的 Unix 套接字(权限 0600,只为同一用户提供服务)与正在运行的 Launchpad 通信。它没有任何特权,也没有自己的状态:bundle 通过 Launchpad 的辅助程序安装,每台虚拟机都通过它自己 Core Bundle 中的 `vphone-cli` 运行。没有任何东西在网络上监听;要从其他机器使用它,请通过 ssh 连接。
+
+## 另请参阅
+
+- [Core Bundle 与本地构建](core-bundles.md)
+- [Bundle 集成](bundle-integration.md)
+- [创建与运行](../machines/create-and-run.md)
diff --git a/Documents/zh/machines/automation-api.md b/Documents/zh/machines/automation-api.md
new file mode 100644
index 00000000..7870a990
--- /dev/null
+++ b/Documents/zh/machines/automation-api.md
@@ -0,0 +1,78 @@
+# 自动化 API
+
+通过 HTTP 和 WebSocket 用脚本控制运行中的虚拟机。本页介绍如何开启 API、完成认证并发出第一批请求;[完整 API 参考](../../../Research/vphoned_http_api.md)列出了所有路由和方法。
+
+## 开启 API
+
+启动虚拟机时加上 `--api-listen`:
+
+```sh
+vphone-cli vm launch myphone --api-listen 127.0.0.1:8765
+```
+
+虚拟机启动后,`vphone-vm` 会打印地址和 token:
+
+```text
+[api] HTTP/WebSocket API: http://127.0.0.1:8765
+[api] token: 3f9c…
+[api] send it as: Authorization: Bearer 3f9c…
+```
+
+- 不加 `--api-listen` 时,宿主机上不会有监听器。
+- 端口设为 `0` 时由 macOS 分配一个空闲端口;实际地址会在虚拟机启动后打印出来。
+- `--api-listen` 不能与 `--dfu` 一起使用。
+
+> [!WARNING]
+> vphoned 以 root 身份运行,API 可以读写客户机中的任何文件、列出钥匙串内容并载入启动守护进程。仅在本机使用时,请监听 `127.0.0.1` 或 `[::1]`。监听其他地址时会打印警告:任何能访问该地址的机器只需要 token 即可控制虚拟机,而 token 在普通 HTTP 上以明文传输,因此只应在可信网络中使用。
+
+## Token
+
+每次启动都会生成新的 token:32 个随机字节,以十六进制表示。要使用固定的 token,请在启动前设置 `VPHONE_API_TOKEN`;`vphone-cli vm launch` 会把自己的环境变量传给 `vphone-vm`。该值必须是 16 到 256 个 `A-Z a-z 0-9 - . _ ~` 中的字符;其他非空值都会导致启动中止。
+
+token 可以用以下任意一种方式发送:
+
+| 方式 | 适用于 |
+| --- | --- |
+| `Authorization: Bearer <token>` 请求头 | HTTP,以及可以设置请求头的 WebSocket 客户端 |
+| `token=<token>` 查询参数 | WebSocket URL,例如 `ws://127.0.0.1:8765/v1/events?token=<token>` |
+| `Sec-WebSocket-Protocol: vphone-token.<token>` | 只能设置子协议的 WebSocket 客户端 |
+
+缺少 token 或 token 错误时返回 `401 Unauthorized`,连接会在任何内容到达客户机之前关闭。
+
+## 请求示例
+
+```sh
+TOKEN=... # from the "[api] token:" line, or the VPHONE_API_TOKEN you set
+
+# Health check
+curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8765/v1/health
+
+# Call any method through /v1/rpc
+curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+ -d '{"method":"device.snapshot","params":{}}' http://127.0.0.1:8765/v1/rpc
+
+# Event stream
+websocat "ws://127.0.0.1:8765/v1/events?token=$TOKEN"
+
+# Interactive shell in the guest (websocat needs --binary)
+websocat --binary "ws://127.0.0.1:8765/v1/shell?token=$TOKEN&cols=120&rows=40"
+```
+
+自行编写客户端时容易出错的规则:
+
+- 每个 `POST` 都必须发送 `Content-Type: application/json`,否则返回 `415`。
+- 带有 `Origin` 请求头的请求,或者 `Host` 不是 `vphoned`、`localhost`、`127.0.0.1` 或 `::1` 的请求,会返回 `403`。这样可以阻止网页访问 API。
+- `GET` 路由只读取。要更改设置,请使用 `PUT` 或 `POST`,例如对 `PUT /v1/low-power-mode` 发送 `{"enabled": true}`。
+
+Swift App 可以使用 `VPhoneAPIKit` 软件包中的 `VPhoneAPIClient`,它会自动发送 token;示例见 API 参考。
+
+## 不使用网络监听器
+
+虚拟机的控制套接字无需 API 监听器也能接受同样的方法:以一行 JSON 发送 `{"t":"rpc","method":"<method>","params":{}}`。见[控制套接字](create-and-run.md)。
+
+## 另请参阅
+
+- [完整 API 参考](../../../Research/vphoned_http_api.md)
+- [创建与运行虚拟机](create-and-run.md)
+- [端口转发](../networking/port-forwarding.md)
+- [Launchpad 命令行](../launchpad/launchpad-cli.md)
diff --git a/Documents/zh/machines/boot-roms.md b/Documents/zh/machines/boot-roms.md
new file mode 100644
index 00000000..1049b2b1
--- /dev/null
+++ b/Documents/zh/machines/boot-roms.md
@@ -0,0 +1,51 @@
+# 启动 ROM
+
+选择虚拟机从哪个启动 ROM 和 SEP 启动 ROM 启动。本页介绍如何查看虚拟机使用的 ROM,以及如何在开源 ROM 与 Apple 的 ROM 之间切换。
+
+## 查看与切换
+
+```sh
+vphone-cli vm info myphone # shows rom and seprom
+vphone-cli vm config myphone --rom openavb --seprom opensep # open-source ROMs
+vphone-cli vm config myphone --rom apple --seprom apple # Apple's ROMs
+```
+
+切换在虚拟机下次启动时生效,不需要重新恢复系统,两个方向都可以切换。
+
+| 选项 | 值 | ROM |
+| --- | --- | --- |
+| `--rom` | `openavb` | bundle 中的 OpenAVB |
+| `--rom` | `apple` | Virtualization.framework 的 AVPBooter(如果虚拟机有自己打过补丁的副本,则使用该副本) |
+| `--rom` | 文件路径 | 任何其他启动 ROM |
+| `--seprom` | `opensep` | bundle 中的 OpenSEP |
+| `--seprom` | `apple` | Virtualization.framework 的 AVPSEPBooter |
+| `--seprom` | 文件路径 | 任何其他 SEP 启动 ROM |
+
+两种启动 ROM 载入的是同一个打过补丁的 LLB,两种 SEP ROM 载入的都是恢复时安装的 SEP 固件,因此不需要重新恢复。
+
+> [!NOTE]
+> 恢复使用 OpenAVB 启动的虚拟机,需要 `VPhone.bundle` 2.10.1 或更新版本。
+
+## 虚拟机使用哪些 ROM
+
+新建的虚拟机不使用 Virtualization.framework 中的闭源 ROM,而是从两个开源 ROM 启动:
+
+- [OpenAVB](https://github.com/owngoal-dev/OpenAVB) 替代启动 ROM AVPBooter。它不需要打补丁,因此 `fw patch` 不会改动它。
+- [OpenSEP](https://github.com/owngoal-dev/OpenSEP) 替代 SEP 启动 ROM AVPSEPBooter。
+
+两者同时使用时,iBoot 和 SEPOS 之前不会运行任何由 Apple 编写的代码。旧版本创建的虚拟机会继续使用 Apple 的 ROM,直到你切换为止。
+
+## ROM 的来源
+
+两者都以预编译形式随 `VPhone.bundle` 发布,由固定的上游提交构建。各自的 README 说明了如何重新构建并逐字节核对:
+
+- [OpenAVB README](../../../VPhoneExecutable/VPhoneVirtualization/Resources/OpenAVB/README.md)
+- [OpenSEP README](../../../VPhoneExecutable/VPhoneVirtualization/Resources/OpenSEP/README.md)
+
+详细内容见研究记录中的 [OpenAVB](../../../Research/Firmware/openavb_boot_rom.md) 和 [OpenSEP](../../../Research/Firmware/opensep_sep_rom.md)。
+
+## 另请参阅
+
+- [创建与运行虚拟机](create-and-run.md)
+- [固件准备](../firmware/firmware-preparation.md)
+- [故障排查](../help/troubleshooting.md)
diff --git a/Documents/zh/machines/create-and-run.md b/Documents/zh/machines/create-and-run.md
new file mode 100644
index 00000000..3e7bfb57
--- /dev/null
+++ b/Documents/zh/machines/create-and-run.md
@@ -0,0 +1,121 @@
+# 创建与运行虚拟机
+
+在终端中用 `vphone-cli` 创建、启动和停止虚拟机。不使用 Launchpad、用脚本创建虚拟机,或者需要重复执行流程中的某个阶段时,请参阅本页。
+
+Launchpad 通过 `VPhone.bundle` 中的 `vphone-cli` 管理虚拟机;同样的命令也可以在终端中使用:
+
+```sh
+vphone-cli vm list
+vphone-cli vm launch myphone
+vphone-cli vm export myphone --out myphone.tzst
+```
+
+虚拟机保存在 `~/.vphone/`。运行 `vphone-cli <group> --help` 查看全部命令。
+
+## 创建虚拟机
+
+你需要一个 iPhone17,3 恢复 IPSW 和一个兼容的 PCC/cloudOS IPSW,可以是本地路径或 URL。[兼容性](../firmware/compatibility.md)列出了目前已验证的组合。
+
+```sh
+vphone-cli host preflight
+vphone-cli vm create myphone \
+ --iphone-source /path/to/iPhone17,3_Restore.ipsw \
+ --cloudos-source /path/to/cloudOS.ipsw
+```
+
+创建过程依次经过以下阶段:准备、固件补丁、在线 DFU 恢复、在宿主机上装载并安装 CFW、首次图形界面启动。
+
+- 需要联网获取恢复票据。
+- 安装 CFW 需要 root 权限。bundle 不带授权对话框或提权辅助程序,因此需要你自己提供 root 权限。
+- 默认虚拟磁盘为 64 GB。
+
+成功时会以 `[+] First boot: vphoned ping succeeded.` 和 `CFW VM created; vphoned connected. Guest user environment is untouched.` 结束。之后虚拟机会停止:这次 ping 证明 vphoned 在该次启动中作出了响应,同时不会留下运行中的虚拟机。
+
+### 选项
+
+| 选项 | 作用 |
+| --- | --- |
+| `--iphone-version`、`--iphone-build` | 像 `fw prepare` 一样为 `--device`(默认为 iPhone17,3)解析 iPhone IPSW,而不必传入 `--iphone-source`。 |
+| 省略 `--cloudos-source` | 使用目录为该版本推荐的 cloudOS,即 `fw catalog` 列出的那个。 |
+| `--disk-size` | 虚拟磁盘大小,单位为 GB(默认 64)。 |
+| `--preset` | 补丁预设名称,或预设 plist 的路径(默认 `standard`)。运行 `fw patches` 查看每个预设应用哪些补丁。 |
+| `--cpu` | CPU 核心数(默认 8)。 |
+| `--memory` | 内存,单位为 MB(默认 8192)。 |
+| `--network` | `nat`(默认)、`bridged`、`tunnel` 或 `none`。 |
+| `--unlock-at-startup` | `on` 或 `off`(默认)。 |
+| `--no-template` | 单独构建虚拟机,不从模板克隆。 |
+| `--skip-first-boot` | 跳过最后的启动,适用于由调用方自行启动虚拟机的情况。 |
+| `--bootstrap roothide` | 在首次启动时安装软件包环境。见[软件包环境](package-environment.md)。 |
+| `--keep-artifacts` | 保留体积很大的已准备恢复目录。磁盘空间紧张时不要加。 |
+
+`--cpu`、`--memory`、`--network` 和 `--unlock-at-startup` 会为新虚拟机设置与 `vm config` 相同的配置项。
+
+### 模板
+
+默认情况下,流程会先构建一个[模板](../storage/templates.md),再从模板克隆出虚拟机。之后对同一设备、同一 iOS 和 cloudOS 构建版本、同一预设和磁盘大小运行 `vm create` 时,会直接从该模板克隆,不再重新恢复。传入 `--no-template` 可单独构建虚拟机。
+
+### 补丁与固件准备
+
+固件流程只有一种模式。它为启动链和客户机系统打补丁,安装 vphoned,用户环境保持为空:不会安装 Sileo、apt、TrollStore、SSH 服务器或 VNC 服务器。补丁预设决定应用哪些补丁;`vphone-cli fw set-patches` 配合 `--block` 或 `--allow` 可以单独关闭或开启某个补丁。
+
+打补丁之前,创建流程会先准备固件:一次临时的 cloudOS 恢复用于提供 GPU 驱动,不含 vphone600 组件的 cloudOS 需要重新构建 kernelcache。见[固件准备](../firmware/firmware-preparation.md)。要从一份列表创建多台虚拟机,请参阅[批量创建虚拟机](../storage/many-machines.md)。
+
+## 启动与停止
+
+```sh
+vphone-cli vm launch myphone # start the VM window and keep it running
+vphone-cli vm stop myphone # run from another terminal to stop it
+```
+
+`vm launch` 启动客户机时不等待 vphoned;该守护进程会在启动过程中连接。虚拟机窗口和菜单提供主屏幕键和电源键、App 安装和文件浏览。`vm launch --headless` 启动时不显示虚拟机窗口和菜单栏。
+
+以下操作都会正常关闭客户机(vphoned `system.shutdown`):
+
+- 关闭虚拟机窗口
+- ⌘Q
+- `vm stop`
+- 在运行 `vm launch` 的终端中按 Control-C
+
+客户机停止后虚拟机即结束;如果 15 秒后仍未停止,也会结束。vphoned 无法代为响应的客户机(例如处于 DFU 或仍在启动中)会像拔掉电源一样立即关闭。再按一次 Control-C 会直接关闭,不再等待。
+
+`vm stop` 只向虚拟机自己的进程发送信号,即 `vphone-vm` 和 Virtualization 的虚拟机服务。其他打开了磁盘的程序(例如正在计算磁盘大小的 Launchpad、聚焦或备份工具)会被列出名称,但不会被终止。
+
+## 控制套接字
+
+每台运行中的虚拟机在其文件夹中都有一个控制套接字 `vphone.sock`(`~/.vphone/machines/<name>/vphone.sock`):输入一行 JSON,返回一行 JSON。多个连接可以同时处理;没有窗口的虚拟机也有这个套接字,此时 `tap` 和 `swipe` 通过 vphoned 的触摸注入实现,屏幕图像来自客户机。
+
+除了 `tap`、`swipe`、`key` 和 `screenshot`,`rpc` 请求可以调用 [API 参考](../../../Research/vphoned_http_api.md)中的任何 vphoned 方法:
+
+```sh
+printf '%s\n' '{"t":"rpc","method":"device.info","params":{}}' | nc -U ~/.vphone/machines/myphone/vphone.sock
+```
+
+例如,`input.key` 配合 `{"name":"cmd+v"}` 可以粘贴,`input.type` 可以输入文本。这个流程不会安装 SSH 或 VNC 端点。需要 HTTP 和 WebSocket 访问时,请参阅[自动化 API](automation-api.md)。
+
+## 手动运行各个阶段
+
+排查问题或重复某个阶段时使用。`restore` 与虚拟机通信期间,要让 DFU 启动保持运行:
+
+```sh
+vphone-cli vm new myphone
+vphone-cli fw prepare myphone \
+ --iphone-source /path/to/iPhone17,3_Restore.ipsw \
+ --cloudos-source /path/to/cloudOS.ipsw
+vphone-cli fw patch myphone
+
+vphone-cli vm launch myphone --dfu &
+vphone-cli restore myphone
+vphone-cli vm stop myphone
+
+vphone-cli cfw install myphone
+vphone-cli vm launch myphone
+```
+
+在线恢复会在进程内获取票据。离线恢复请参阅 `vphone-cli restore --help` 中的 `--get-shsh` 和 `--offline`。手动流程不会像 `vm create` 那样执行首次启动的 ping 检查。
+
+## 另请参阅
+
+- [模板](../storage/templates.md)
+- [设备名称与时钟](device-name-and-clock.md)
+- [资料库与备份](../storage/library-and-backups.md)
+- [共享磁盘空间](../storage/sharing-disk-space.md)
diff --git a/Documents/zh/machines/device-name-and-clock.md b/Documents/zh/machines/device-name-and-clock.md
new file mode 100644
index 00000000..7dcdbcfa
--- /dev/null
+++ b/Documents/zh/machines/device-name-and-clock.md
@@ -0,0 +1,42 @@
+# 设备名称与时钟
+
+客户机的设备名称来自虚拟机,时钟和时区来自你的 Mac。如果客户机中的名称或时间与预期不符,请参阅本页。
+
+## 设备名称
+
+要更改客户机显示的名称,请重命名虚拟机:
+
+```sh
+vphone-cli vm rename myphone <new-name>
+```
+
+客户机会把虚拟机的名称作为设备名称显示,包括在 Xcode 的设备列表和 `xcrun devicectl list devices` 中。
+
+- 无法在客户机内部,或通过访达、Xcode、`idevicename` 重命名设备。这些地方的重命名会报告成功,但实际上什么都不会改变。
+- 运行 `vm rename` 后,访达和 `ideviceinfo` 会在虚拟机启动后立即显示新名称。Xcode 和 `devicectl` 在设备出现时读取名称,可能要到再下一次启动才显示新名称。
+- 如果虚拟机名称超过 255 个 UTF-8 字节或包含控制字符,则不会被使用;此时客户机显示它自己的名称。
+
+每次启动几秒后,`vphone-vm` 连接到 vphoned 时都会把名称传给客户机,客户机会保留这个名称供下次启动使用。客户机自己的名称仍保存在其偏好设置中,不会被改动。
+
+现有虚拟机迁移到带有此功能的 bundle 后,会在环境更新时获得新的客户机库,并从之后的那次启动开始使用。
+
+实现细节见 [`Research/Guest/device_name_pinning.md`](../../../Research/Guest/device_name_pinning.md)。
+
+## 时钟与时区
+
+客户机跟随 Mac 的时区和时钟,无需任何设置。
+
+每次连接到 vphoned 时,`vphone-vm` 都会发送 Mac 的时区和当时的时间,之后每分钟再发送一次时间。关机一天的客户机,或者在睡眠的 Mac 上挂起的客户机,无需访问 NTP 服务器,一分钟内就会回到 Mac 的时间。与 Mac 相差不到一秒的客户机不会被调整。
+
+要让客户机使用不同的日期或时间:
+
+1. 在客户机中打开**设置 > 通用 > 日期与时间**。
+2. 选择日期或时间。这会关闭客户机的自动时间,Mac 的时间也不再应用。
+
+要恢复使用 Mac 的时间,请在同一位置重新打开**自动设置**。
+
+## 另请参阅
+
+- [创建与运行虚拟机](create-and-run.md)
+- [资料库与备份](../storage/library-and-backups.md)
+- [网络](../networking/overview.md)
diff --git a/Documents/zh/machines/package-environment.md b/Documents/zh/machines/package-environment.md
new file mode 100644
index 00000000..61103582
--- /dev/null
+++ b/Documents/zh/machines/package-environment.md
@@ -0,0 +1,50 @@
+# 软件包环境
+
+在虚拟机中安装或删除软件包管理器。新建的虚拟机没有软件包管理器;需要在客户机中使用 `apt`、shell、SSH 或其他命令行工具时,请按本页操作。
+
+## 安装
+
+1. 在虚拟机窗口的菜单栏中选择 **Apps > Install Bootstrap…**,布局选择 **roothide**(**rootless** 已弃用)。这会在虚拟机中安装 Irisin。
+2. 在 Irisin 中打开 **OwnGoal Packages** 软件源,找到 **OwnGoal Bootstrap for vphone**(`owngoal-bootstrap-vphone`),用 **Bootstrap Install** 安装。
+3. 首次安装完成后,其余软件包按普通方式安装即可。
+
+`owngoal-bootstrap-vphone` 会一次装好虚拟机需要的全部内容:`apt` 和 `dpkg`、`bash`、`zsh` 和 `dash`、`sudo`、核心命令行工具、`openssh-server`、`curl`、`wget`、`vim`、`git`、`uikittools`、`launchctl`,以及 OwnGoal 的几个 App。
+
+> [!WARNING]
+> 不要逐个安装这些软件包。其中一些相互依赖,`openssh-server` 的部分依赖声明还存在循环,分别安装可能在中途失败。
+
+如果首次安装失败,不要在原环境上修复。请选择 **Apps > Uninstall Bootstrap…**,然后从第 1 步重新开始。
+
+### 在创建虚拟机时安装
+
+```sh
+vphone-cli vm create myphone --bootstrap roothide ...
+```
+
+`--bootstrap roothide` 会在新虚拟机首次启动时完成第 1 步和第 2 步:先安装 Irisin,再通过 `irisin-cli` 从 Irisin 推荐的软件源以 Bootstrap Install 方式安装 `owngoal-bootstrap-vphone`。第 2 步要求 Irisin 的 `irisin-cli install` 支持 `--repository` 和 `--bootstrap-install`。
+
+## 删除
+
+选择 **Apps > Uninstall Bootstrap…**。删除后虚拟机会重启。
+
+Irisin 把自己的数据(下载内容、日志、设置)保存在其主目录下的 `Documents/wiki.qaq.irisin` 中:
+
+| 布局 | Irisin 的主目录 | 卸载后 |
+| --- | --- | --- |
+| roothide | 环境自己的 `/var/mobile` | 数据随其他内容一起删除。 |
+| rootless | 系统的 `/var/mobile` | 数据会保留。 |
+
+## 更多选项
+
+按住 Option 键打开 **Apps** 菜单,会多出两个选项:
+
+- **Install Bootstrap from File…**:使用本地的 Irisin `.deb` 安装。
+- **Uninstall Bootstrap Without Restarting…**:删除环境,但不重启虚拟机。
+
+自动化 API 也提供同样的操作(`bootstrap.install`、`bootstrap.status`)。见 [API 参考](../../../Research/vphoned_http_api.md)。
+
+## 另请参阅
+
+- [创建与运行虚拟机](create-and-run.md)
+- [自动化 API](automation-api.md)
+- [故障排查](../help/troubleshooting.md)
diff --git a/Documents/zh/networking/addresses.md b/Documents/zh/networking/addresses.md
new file mode 100644
index 00000000..bd3804bc
--- /dev/null
+++ b/Documents/zh/networking/addresses.md
@@ -0,0 +1,80 @@
+# MAC 与 IP 地址
+
+本页介绍客户机保存的 MAC 地址、如何释放旧 MAC 地址仍占用的 DHCP 租约,以及如何为客户机设置固定 IPv4 地址。
+
+## MAC 地址
+
+首次启动时,客户机的网卡会获得一个随机的本地管理 MAC 地址,并像机器标识符一样保存在 `config.plist` 中。这样客户机在多次启动之间始终保持同一个身份和同一个 DHCP 租约。
+
+设置或更换 MAC 地址:
+
+```sh
+vphone-cli vm config <name> --mac 02:11:22:33:44:55
+vphone-cli vm config <name> --mac random # a new one now
+vphone-cli vm config <name> --mac auto # a new one at the next launch
+```
+
+克隆的虚拟机会像保留机器标识符一样保留原虚拟机的 MAC 地址。要同时运行两者,请用 `vm clone --new-identity` 克隆(这会给副本新的身份和 MAC 地址),或者为副本设置新的 MAC 地址。`--new-identity` 还会清除副本的固定地址、端口转发和 mDNS 名称。
+
+## 旧 MAC 地址占用的地址
+
+症状:在 `nat` 模式下,新客户机获得的地址越来越大,直到撞上你在地址范围高位设置的固定地址。
+
+列出共享网络上的租约及各自的所有者,然后释放孤立租约(需要 `VPhone.bundle` 2.5 或更新版本):
+
+```sh
+vphone-cli vm leases
+sudo vphone-cli vm leases --release-orphans
+```
+
+通过 Launchpad:
+
+```sh
+vphone-launchpad-cli vm leases
+vphone-launchpad-cli vm leases --release
+```
+
+在 Launchpad 窗口中,Host Setup(宿主机设置)会在 NAT Network 下显示孤立租约的数量,点击 Release… 并经管理员批准后即可释放。Launchpad 会与它列出的每个资料库进行比对。
+
+孤立租约是指 iOS 或 iPadOS 客户机的租约,其 MAC 地址不属于资料库中的任何虚拟机,且租约已经过期。`--release-orphans` 会从 `/var/db/dhcpd_leases` 中删除孤立租约,并让 DHCP 服务器重新读取该文件,因此需要 root 权限。它永远不会改动:
+
+- 虚拟机自己的租约,即使该租约在虚拟机停止期间已经过期;
+- 尚未过期的租约,例如刚更换了 MAC 地址的运行中客户机的租约;
+- 其他虚拟机 App 的租约,或者通过互联网共享连接的设备的租约。
+
+其他资料库中的虚拟机只有在同时指定了该资料库时才会计入:每个资料库都要重复一次 `--library-root`。如果某个资料库中没有虚拟机,或者某台虚拟机的设置无法读取,释放操作会拒绝执行,因为此时那里的每个租约看起来都是孤立的。
+
+原因:Mac 的 DHCP 服务器会让每个地址始终绑定到最初分配给它的 MAC 地址,即使租约已过期也是如此;只有当范围内的其他地址都已被占用时,才会把它分配给别人。删除虚拟机或更换其 MAC 地址后,它的地址仍绑定到一个不再使用的 MAC 地址;在开始保存 MAC 地址之前进行的每次启动也是如此。
+
+## 固定地址
+
+`--ip` 为客户机设置固定 IPv4 地址。不带前缀长度时默认为 `/24`。`--gateway` 和 `--dns` 是可选的;设为 `auto` 会恢复默认值。`--ip dhcp` 删除固定地址。
+
+```sh
+vphone-cli vm config <name> --ip 192.168.65.50
+vphone-cli vm config <name> --network tunnel --ip 10.20.0.5/16 --dns 1.1.1.1
+vphone-cli vm config <name> --ip dhcp
+```
+
+地址如何传给客户机取决于网络模式:
+
+| 模式 | 地址 | 应用方式 |
+| --- | --- | --- |
+| `nat` | 位于 Mac 的共享 NAT 网络上:通常是 `192.168.65.0/24`,设置了 `--nat-peers off` 的虚拟机则是 `192.168.64.0/24`(见[虚拟机互访](peers.md)) | vphoned 把它写入客户机的网络设置。网关和 DNS 都是 Mac,即 `192.168.65.1` 或 `192.168.64.1`。 |
+| `tunnel` | 任意私有子网 | 由隧道自己的 DHCP 分配。网关同时也是 DNS 解析器,默认为子网的第一个地址,除非 `--gateway` 指定了其他地址。 |
+| `bridged` | 物理网络上的地址 | vphoned 把它写入客户机。请把 `--gateway` 和 `--dns` 设为该网络自己的值。 |
+
+> [!TIP]
+> 共享 `nat` 网络上的地址不会在 Mac 的 DHCP 服务器中预留。请在范围高位选择一个地址(例如 `.200`),这样的地址不太可能已被 DHCP 分配给其他虚拟机。
+
+在 `nat` 模式下,地址必须位于虚拟机所加入的共享网络上:可以互访的虚拟机(默认)使用第二个网络(`192.168.65.0/24`),设置了 `--nat-peers off` 的使用第一个网络(`192.168.64.0/24`)。如果 vmnet 的 `Shared_Net_Address` 被移动过,两者都会随之变化。要使用其他子网,请使用 `tunnel`。
+
+每次 `vphone-vm` 连接到 vphoned 时,vphoned 都会应用该地址,因此客户机中的地址如果在 Mac 不知情时被改动,也会被改回来。它只撤销自己的设置:虚拟机改回 DHCP 时,在客户机“设置”App 中手动输入的地址不会被改动。
+
+macOS 26 可以为虚拟机提供独立的 NAT 网络,但虚拟机停止后该子网仍会被保留(测试中 40 分钟后仍被保留),在此期间所有使用它的启动都会失败,因此 vphone 不使用这一功能。
+
+## 另请参阅
+
+- [网络](overview.md)
+- [端口转发](port-forwarding.md)
+- [虚拟机互访](peers.md)
diff --git a/Documents/zh/networking/names.md b/Documents/zh/networking/names.md
new file mode 100644
index 00000000..27c4733c
--- /dev/null
+++ b/Documents/zh/networking/names.md
@@ -0,0 +1,70 @@
+# 网络上的名称
+
+本页介绍两个名称:客户机自己的 `.local` 名称,让 Mac 可以按名称访问它;以及客户机解析出的这台 Mac 的 `.local` 名称。
+
+## 客户机的名称(mDNS)
+
+默认关闭。开启后即可按名称访问客户机:
+
+```sh
+vphone-cli vm config <name> --mdns on
+ping <vm-name>.local
+```
+
+| 设置 | 作用 |
+| --- | --- |
+| `--mdns on` | 客户机响应 `<vm-name>.local`。虚拟机名称中字母和数字以外的字符都会变成连字符:`ipad_pro.13` 会变成 `ipad-pro-13.local`。 |
+| `--mdns <name>` | 客户机响应你指定的其他名称。 |
+| `--mdns off` | 恢复客户机自己的名称。 |
+
+该名称在所有模式下都有效,包括 `none`:
+
+| 模式 | `<name>.local` 解析为 |
+| --- | --- |
+| `nat` | 客户机在共享网络上的地址,以及它的 USB 链路地址 |
+| `bridged` | 客户机的局域网地址(局域网中的每台设备都能解析),以及它在 Mac 上的 USB 链路地址 |
+| `tunnel`、`none` | 客户机的 USB 链路地址,仅限 Mac 上 |
+
+除了网卡之外,客户机还有一条网络链路,就像通过 USB 连接的 iPhone 提供给 Mac 的那样。它在 Mac 上显示为一个带 `169.254` 地址的 `en` 接口。这个地址是链路本地地址,但 Mac 可以直接通过它访问客户机,因此在 `tunnel` 模式下,连接 `<name>.local` 无需端口转发即可访问客户机上的服务。
+
+注意事项:
+
+- 如果其他设备已在使用该名称,mDNS 会为客户机改名(`name-2`)。
+- `vm rename` 会重命名由 `--mdns on` 根据虚拟机名称生成的名称;你手动指定的名称保持不变。
+- 用 `vm stop` 或关闭窗口停止的虚拟机无法撤回它的通告。Mac 的解析器会继续返回旧地址,直到缓存的记录过期;主机地址的过期时间为 75 分钟(TTL 4500 秒)。
+
+每次 `vphone-vm` 连接时,vphoned 都会在客户机的网络设置中设置该名称(`LocalHostName`),客户机的 mDNSResponder 会在它的每条链路上通告该名称。
+
+## 客户机中这台 Mac 的名称
+
+默认开启。客户机会立即把这台 Mac 的 mDNS 名称(`scutil --get LocalHostName` 加上 `.local`)解析为它访问 Mac 所用的地址:
+
+| 模式 | 客户机中的 `<Mac>.local` |
+| --- | --- |
+| `nat` | 共享网络上的 Mac,通常是 `192.168.65.1`(设置 `--nat-peers off` 时为 `192.168.64.1`) |
+| `tunnel` | 网关,默认为 `192.168.127.1`。连接它会到达 Mac 的回环地址(`127.0.0.1`),就像 QEMU 和 VirtualBox 中的 `10.0.2.2` 一样 |
+| `bridged` | Mac 在桥接接口上的地址 |
+
+撤回该名称:
+
+```sh
+vphone-cli vm config <name> --mac-name off
+```
+
+查看客户机的解析器返回什么,以及每个地址能否连接:
+
+```sh
+vphone-launchpad-cli guest rpc <name> network.resolve '{"host":"<Mac>.local","family":"ipv4","port":8000}'
+```
+
+### 为什么需要它
+
+如果只依靠 mDNS,在客户机中对 Mac 名称进行 IPv4 查询可能会失败。客户机还会在 USB 链路上收到 Mac 的响应,而 Mac 在该链路上没有 IPv4 地址,会回答“没有该记录”。哪条链路先回答就决定了查询结果,因此需要 IPv4 地址的 App 会一直收到错误,直到从另一条链路缓存了真正的答案为止。查询结果还会把 Mac 在 USB 链路上的 `169.254` 地址排在最前面;iOS 通过主接口路由 `169.254.0.0/16`,因此连接该地址的普通套接字可能会从 `en0` 发出,而那里没有任何响应,只能等到超时。
+
+vphoned 会把该名称作为本地记录注册到客户机自己的 mDNSResponder 中,效果类似 `/etc/hosts` 中的一行:它会立即用这一个地址回答 IPv4 查询,既不询问网络,也不使用已缓存的答案。每次 `vphone-vm` 连接时它都会这样做,vphoned 启动时也会再做一次,因此重启后在 App 运行之前名称就已就绪。客户机的系统宗卷是只读的,因此不会编辑 `/etc/hosts` 本身,也不会在任何网络上进行通告。IPv6 查询仍交给 mDNS。
+
+## 另请参阅
+
+- [网络](overview.md)
+- [MAC 与 IP 地址](addresses.md)
+- [隧道模式](tunnel.md)
diff --git a/Documents/zh/networking/overview.md b/Documents/zh/networking/overview.md
new file mode 100644
index 00000000..948fd90a
--- /dev/null
+++ b/Documents/zh/networking/overview.md
@@ -0,0 +1,56 @@
+# 网络
+
+每台虚拟机有一种网络模式。本页介绍如何选择网络模式,以及如何为运行中的虚拟机断开网络;本节的其他页面介绍隧道模式、地址、端口转发、名称以及虚拟机互访。
+
+## 网络模式
+
+| 模式 | 客户机如何访问互联网 | 适用情况 |
+| --- | --- | --- |
+| `nat` | Virtualization.framework 内置的 NAT | 默认模式。Mac 没有使用 VPN,或者 VPN 不需要承载客户机的流量。 |
+| `bridged` | 直接接入 Mac 的某个物理接口,在该网络上拥有自己的地址 | 客户机需要能被局域网中的其他机器访问。 |
+| [`tunnel`](tunnel.md) | 通过 `vphone-vm` 在 Mac 上建立的普通连接 | Mac 的流量经过 VPN 或代理 App,客户机的流量也必须同样经过它。 |
+| `none` | 没有网络设备 | 客户机必须保持离线。 |
+
+网络模式保存在虚拟机的 `config.plist` 中,在虚拟机启动时读取,因此更改会在下次启动时生效。
+
+## 选择模式
+
+在 Launchpad 中:
+
+1. 停止虚拟机。
+2. 在 `⋯` 菜单或右键菜单中选择 Settings…(设置)。
+3. 在 Network(网络)部分选择模式。
+
+New Machine(新建虚拟机)在 Advanced Options(高级选项)中设置模式。选中一台虚拟机时,Settings… 中还有 Address(地址)和 Port Forwarding(端口转发)部分。
+
+在命令行中:
+
+```sh
+vphone-cli vm config <name> --network tunnel
+# or through Launchpad
+vphone-launchpad-cli exec vm config <name> --network tunnel
+```
+
+`tunnel` 需要在 `vphone-cli vm config --help` 中列出了该模式的 `VPhone.bundle`。较旧的 bundle 会拒绝这项设置。
+
+## 为运行中的虚拟机断开网络
+
+`vm network` 作用于运行中的虚拟机,它所做的一切都不会被保存:
+
+```sh
+vphone-cli vm network <name> # state of the NIC
+vphone-cli vm network <name> --link down # unplug the cable
+vphone-cli vm network <name> --link up # plug it back in
+```
+
+客户机会看到链路断开后又恢复。同样的请求也可以通过 `vphone.sock` 以 `{"t":"network"}` 发送,并附带 `"link":"down"` 或 `"link":"up"`。
+
+> [!NOTE]
+> 运行中的虚拟机无法切换到其他网络。Virtualization 会接受这项更改,然后以内部错误停止虚拟机,因此 `vm network` 只会恢复虚拟机启动时所用的网络。要更改模式,请使用 `vm config` 并重新启动虚拟机。
+
+## 另请参阅
+
+- [隧道模式](tunnel.md):Mac 使用 VPN 或代理 App 时
+- [MAC 与 IP 地址](addresses.md):保存的 MAC 地址、旧 MAC 地址占用的租约、固定地址
+- [端口转发](port-forwarding.md):把 Mac 上的端口转发到客户机
+- [网络上的名称](names.md)和[虚拟机互访](peers.md)
diff --git a/Documents/zh/networking/peers.md b/Documents/zh/networking/peers.md
new file mode 100644
index 00000000..7cfb72a1
--- /dev/null
+++ b/Documents/zh/networking/peers.md
@@ -0,0 +1,33 @@
+# 虚拟机互访
+
+同一台 Mac 上的 `nat` 虚拟机可以直接互相访问,包括 Bonjour。虚拟 Apple Watch 就是这样与虚拟 iPhone 配对的。本页介绍如何把某台虚拟机隔离开。
+
+## 隔离虚拟机
+
+```sh
+vphone-cli vm config <name> --nat-peers off # isolate this guest again
+vphone-cli vm config <name> --nat-peers on # the default
+```
+
+在 Launchpad 中,对应虚拟机 Network(网络)设置中的“Reach other NAT machines”。更改在下次启动时生效。
+
+被隔离的客户机可以访问 Mac 和互联网,但无法访问其他虚拟机。隔离是每台虚拟机自身网络连接的设置,因此选择退出的虚拟机无论其他虚拟机如何设置,都会保持隔离。
+
+## 虚拟机所在的网络
+
+| 设置 | 共享网络 | Mac 的地址 |
+| --- | --- | --- |
+| `--nat-peers on`(默认) | `192.168.65.0/24` | `192.168.65.1` |
+| `--nat-peers off` | `192.168.64.0/24` | `192.168.64.1` |
+
+[固定地址](addresses.md)(`--ip`)必须位于虚拟机所加入的网络上。固定地址在第一个网络(`192.168.64.0/24`)上的虚拟机会保持隔离,除非它请求与其他虚拟机互访,此时它需要第二个网络上的地址。
+
+## 背景
+
+默认情况下,Virtualization.framework 会在 Mac 的共享网络上把每个 `nat` 客户机与其他客户机隔离开。vphone 关闭了这种隔离,vmnet 随后会把可以互访的虚拟机放到第二个共享网络上,即紧接在第一个网络之后的地址块。这个开关是 Virtualization.framework 的私有接口;不支持它的版本会让所有客户机保持隔离,并在虚拟机启动时给出提示。
+
+## 另请参阅
+
+- [网络](overview.md)
+- [MAC 与 IP 地址](addresses.md)
+- [网络上的名称](names.md)
diff --git a/Documents/zh/networking/port-forwarding.md b/Documents/zh/networking/port-forwarding.md
new file mode 100644
index 00000000..5466d37d
--- /dev/null
+++ b/Documents/zh/networking/port-forwarding.md
@@ -0,0 +1,40 @@
+# 端口转发
+
+在 `nat` 和 `tunnel` 模式下,用 `--forward` 把 Mac 上的端口转发到客户机。`bridged` 模式下客户机以自己的地址接入局域网,因此不需要转发。
+
+## 添加和删除转发
+
+```sh
+vphone-cli vm config <name> --forward tcp:8022:22
+vphone-cli vm config <name> --forward udp:0.0.0.0:5353:53
+vphone-cli vm config <name> --remove-forward 8022
+vphone-cli vm config <name> --clear-forwards
+```
+
+格式为:
+
+```text
+[tcp|udp:][host-address:]host-port:guest-port
+```
+
+| 部分 | 含义 |
+| --- | --- |
+| `tcp` 或 `udp` | 协议 |
+| `host-address` | 转发在 Mac 上监听的地址。默认为 `127.0.0.1`;设为 `0.0.0.0` 后局域网中的其他设备也能访问。 |
+| `host-port` | Mac 上的端口 |
+| `guest-port` | 客户机中的端口 |
+
+要转发更多端口,请重复使用 `--forward`。在 Launchpad 中,虚拟机的 Settings…(设置)中有 Port Forwarding(端口转发)部分。
+
+## 转发的行为
+
+- `vphone-vm` 在虚拟机启动时打开监听器,在虚拟机停止时关闭。
+- 在 `nat` 模式下,它连接到客户机的地址:[固定地址](addresses.md),或 vphoned 报告的地址。
+- 在 `tunnel` 模式下,连接到达客户机时看起来来自网关。
+- 如果 Mac 上的某个端口已被占用,会在虚拟机日志中报告并跳过;其他转发仍然有效。
+
+## 另请参阅
+
+- [网络](overview.md)
+- [隧道模式](tunnel.md)
+- [MAC 与 IP 地址](addresses.md)
diff --git a/Documents/zh/networking/tunnel.md b/Documents/zh/networking/tunnel.md
new file mode 100644
index 00000000..c5a017b8
--- /dev/null
+++ b/Documents/zh/networking/tunnel.md
@@ -0,0 +1,66 @@
+# 隧道模式
+
+当 Mac 的流量经过 VPN 或代理 App,而客户机的流量也必须走同样的路径时,请使用 `tunnel` 模式。在 `nat` 和 `bridged` 模式下,客户机的数据包会绕过 VPN。
+
+## 开启
+
+停止虚拟机,然后运行:
+
+```sh
+vphone-cli vm config <name> --network tunnel
+```
+
+在 Launchpad 中,在虚拟机 Settings…(设置)的 Network(网络)部分选择 `tunnel`。bundle 必须在 `vphone-cli vm config --help` 中列出 `tunnel`;较旧的 bundle 会拒绝该设置。
+
+## 检查是否生效
+
+1. 启动虚拟机,等待它完成启动。
+2. 读取客户机的地址:
+
+ ```sh
+ vphone-launchpad-cli guest rpc <name> device.network
+ ```
+
+ `en0` 应显示 `192.168.127.3`。如果只显示 `fe80::` 地址,说明 DHCP 尚未完成。请等几秒钟再试。
+3. 在客户机中打开一个网页:
+
+ ```sh
+ vphone-launchpad-cli guest rpc <name> apps.open_url '{"url":"https://example.com"}'
+ ```
+
+4. 在 Mac 上确认这些连接属于 `vphone-vm`,并且使用的是 VPN 的地址:
+
+ ```sh
+ lsof -nP -a -i -p "$(pgrep -f 'vphone-vm.*<name>')"
+ ```
+
+## 客户机看到的网络
+
+| 项目 | 值 |
+| --- | --- |
+| 客户机地址 | 由 DHCP 分配的 `192.168.127.3/24`,或[固定地址](addresses.md) |
+| 网关和 DNS | `192.168.127.1`,或固定地址所在子网的第一个地址 |
+| MTU | 1500 |
+| DNS | 发往 `192.168.127.1` 的查询会交给 Mac 的解析器 |
+| 发往网关的其他连接 | Mac 的回环地址 `127.0.0.1`(TCP 和 UDP) |
+
+在代理 App 中,客户机会显示为一个独立的客户端,以虚拟机的名称命名,App 的规则会像对其他 App 一样应用于它。
+
+## 限制
+
+- **仅支持 IPv4。** 客户机不会获得 IPv6 地址,IPv6 流量会被丢弃。
+- **除转发端口外,只能向外连接。** Mac 或局域网上的任何设备都无法通过这个网络访问客户机,[端口转发](port-forwarding.md)中列出的端口除外。USB 访问(`iproxy`、`ideviceinstaller`)和 `vphone.sock` 不使用客户机网络,因此仍可正常使用。`.local` 名称也能通过 USB 链路访问客户机;见[网络上的名称](names.md)。
+- **ping 只能到达网关。** 发往互联网的 ICMP 不会被转发,因此即使 TCP 和 UDP 正常,在客户机中运行 `ping 1.1.1.1` 也会失败。
+- **吞吐量受限于 `vphone-vm`。** 每个数据包都在该进程中处理。下载和视频都能正常使用,但不涉及 VPN 时 `nat` 更快。
+
+## 工作原理
+
+当 VPN 接管了 Mac 的默认路由(WireGuard、Cloudflare WARP,或者以 TUN 模式运行的代理 App,如 Surge 或 Clash)时,`nat` 和 `bridged` 通过物理接口发出的数据包会绕过 VPN。它们要么以未加密的形式发出,要么根本发不出去。
+
+在 `tunnel` 模式下,客户机的网卡在 `vphone-vm` 内部实现。它为网关响应 DHCP、ARP 和 ping,并把客户机的每个 TCP 连接和 UDP 流转换为 Mac 上的普通套接字。这些套接字像其他 App 的套接字一样遵循 Mac 的路由表,因此会由 VPN 承载。它不需要 root 权限,不需要新的网络接口,也不需要更改 Mac 的网络设置。
+
+## 另请参阅
+
+- [网络](overview.md)
+- [MAC 与 IP 地址](addresses.md)
+- [端口转发](port-forwarding.md)
diff --git a/Documents/zh/storage/library-and-backups.md b/Documents/zh/storage/library-and-backups.md
new file mode 100644
index 00000000..6c04d75b
--- /dev/null
+++ b/Documents/zh/storage/library-and-backups.md
@@ -0,0 +1,69 @@
+# 资料库、固件与备份
+
+vphone 把虚拟机和下载的固件保存在哪里、如何移动它们,以及如何拷贝、备份和恢复虚拟机。规划磁盘空间、迁移资料库,或者需要虚拟机的第二份副本时,请参阅本页。
+
+## 备份、拷贝与恢复
+
+```sh
+vphone-cli vm list
+vphone-cli vm info myphone
+vphone-cli vm clone myphone copy # backup: same identity
+vphone-cli vm clone myphone second --new-identity # a second device
+vphone-cli vm export myphone --out myphone.tzst
+vphone-cli vm import myphone.tzst --name restored
+```
+
+`vm clone` 拷贝一台已停止的虚拟机,可用时使用 APFS 写时拷贝。源虚拟机运行时会拒绝执行。
+
+| 克隆方式 | 身份 | 用途 |
+| --- | --- | --- |
+| 普通 `vm clone` | 相同的机器标识符和 MAC 地址 | 备份。不能与原虚拟机同时运行。 |
+| `vm clone --new-identity` | 新的机器标识符(ECID),因而也有新的 UDID;首次启动时获得新的 MAC 地址 | 可与原虚拟机同时运行的第二台设备 |
+
+使用 `--new-identity` 的副本:
+
+- 会清除固定 IPv4 地址、端口转发和手动指定的 mDNS 名称,因为它们会与原虚拟机冲突。由 `--mdns on` 根据原虚拟机名称生成的 mDNS 名称会像重命名时一样跟随新名称。如有需要,请用 `vm config` 重新设置。
+- 保留原虚拟机的数据、App 和设置;不需要重新恢复。
+- 需要你解锁它并再次信任这台 Mac,之后 `ideviceinstaller` 等 lockdown 工具才能使用。
+- 在 APFS 上与原虚拟机共享磁盘块,只保存自己改动的部分,首次启动几次后约为 0.35 GB;不过 `du` 和访达会把每台都按完整大小计算。
+
+> [!WARNING]
+> 不要在虚拟机之间互换 `SEPStorage`、`nvram.bin` 或磁盘映像。它们是同一次恢复一起生成的,SEP 存储与磁盘不匹配的客户机会在启动时 panic。
+
+## 文件存放位置
+
+| 默认路径 | 内容 |
+| --- | --- |
+| `~/.vphone/machines/<name>/` | 一台虚拟机,包括其磁盘、`config.plist` 和补丁工作文件 |
+| `~/.vphone/ipsws/` | 远程来源的 IPSW,所有虚拟机共用;本地 IPSW 在原位置读取 |
+| `~/.vphone/gpu-drivers/<version>_<build>/` | 从 cloudOS 中提取的 GPU 驱动 bundle,所有虚拟机共用 |
+| `~/.vphone/kernelcache/` | 不含 vphone600 组件的 cloudOS 版本所用的 kernelcache 组合、准备好的宗卷,以及从供体中提取的内容 |
+
+移动位置:
+
+| 设置 | 移动的内容 |
+| --- | --- |
+| `VPHONE_ROOT` | 整个 `~/.vphone` 数据根目录:虚拟机资料库和各类缓存 |
+| `VPHONE_LIBRARY_ROOT` | 仅虚拟机资料库;优先于 `VPHONE_ROOT` |
+| `vm create` 和 `fw prepare` 的 `--ipsw-cache <dir>` | 仅 IPSW 缓存 |
+
+## IPSW 缓存与下载
+
+下载的 IPSW 会一直缓存到你删除为止,因此用同一 URL 创建第二台虚拟机时无需再下载。在 Launchpad 中,可以通过 **File > Downloaded IPSWs…** 删除它们。
+
+`vm create` 成功后,准备好的恢复目录会被删除,除非传入了 `--keep-artifacts`。旧版本准备的虚拟机可能仍有一个 `.ipsw-cache/` 目录;可以放心删除,`vm export` 也不会包含它。
+
+如果服务器支持 HTTP 范围请求(Apple 的 CDN 支持),远程 IPSW 会同时通过四个连接下载。每个连接依次获取 32 MB 的分段,分段中断后会从中断处继续。`fw prepare` 的 `--download-connections <n>` 用于设置连接数,范围为 1 到 16。设为 1 时 IPSW 以单一数据流下载,不支持范围请求的服务器也是这样处理。
+
+## 磁盘空间与内存
+
+占用资源较多的创建任务请一次只运行一个。IPSW 和临时恢复目录会占用大量磁盘空间,为大型缓存打补丁也可能占用很多内存。开始创建第二台虚拟机之前,请检查可用空间。
+
+如果资料库位于已装载的外置宗卷上,Launchpad 会把 CFW 临时文件放在该宗卷上。独立运行的 `vphone-cli cfw install` 默认使用 `/private/var/tmp`,也可以用 `--work-parent` 指定一个 root 拥有的私有目录。
+
+## 另请参阅
+
+- [快照](snapshots.md)
+- [模板](templates.md)
+- [在虚拟机之间共享磁盘空间](sharing-disk-space.md)
+- [创建与运行虚拟机](../machines/create-and-run.md)
diff --git a/Documents/zh/storage/many-machines.md b/Documents/zh/storage/many-machines.md
new file mode 100644
index 00000000..4ee2c59d
--- /dev/null
+++ b/Documents/zh/storage/many-machines.md
@@ -0,0 +1,61 @@
+# 批量创建虚拟机
+
+`vm create-bulk` 按顺序创建 plist 中描述的每台虚拟机。可以用它从一个文件搭建实验室或 CI 虚拟机群。
+
+## 运行
+
+```sh
+vphone-cli vm create-bulk list.plist --dry-run # print each machine's vm create command
+vphone-cli vm create-bulk list.plist
+```
+
+与 `vm create` 一样,当某台虚拟机需要构建时,请用 `sudo` 运行。
+
+## 编写列表
+
+```xml
+<dict>
+ <key>version</key> <integer>1</integer>
+ <key>defaults</key>
+ <dict>
+ <key>library-root</key> <string>~/vphone-lab</string>
+ <key>iphone-version</key> <string>26.1</string>
+ <key>preset</key> <string>presets/lab.plist</string>
+ <key>cpu</key> <integer>4</integer>
+ </dict>
+ <key>machines</key>
+ <array>
+ <dict><key>name</key> <string>ci-1</string></dict>
+ <dict><key>name</key> <string>ci-2</string></dict>
+ <dict>
+ <key>name</key> <string>fuzz</string>
+ <key>iphone-build</key> <string>23F77</string>
+ <key>iphone-version</key> <false/>
+ <key>no-template</key> <true/>
+ </dict>
+ </array>
+</dict>
+```
+
+- 每个键是 `vm create` 选项的长名称,后面跟它的值:字符串或整数,标志用 `true`,`keep-apps` 用数组。
+- `defaults` 适用于每台虚拟机。虚拟机自己的键优先,`false` 会清除默认值。
+- 相对路径以 plist 所在的文件夹为基准解析。
+- `library-root` 把虚拟机放到另一个资料库中;命令行中的 `-l` 会覆盖它。
+- 每台虚拟机都必须指定固件(`iphone-version`、`iphone-build`,或 `iphone-source` 加 `cloudos-source`)或 `template`,这样运行过程中不会出现任何提示。
+
+## 运行方式
+
+在创建第一台虚拟机之前,所有虚拟机都会像 `vm create` 那样接受检查。虚拟机按顺序创建,因此模板键相同的虚拟机会克隆第一台构建出的模板。遇到第一个失败就会停止运行。
+
+名称已存在会被视为错误。有两个标志可以改变这一行为,但不能同时使用:
+
+| 标志 | 作用 |
+| --- | --- |
+| `--skip-existing` | 跳过名称已存在的虚拟机,这样中途停止的运行可以再次执行,以创建剩下的虚拟机。失败的虚拟机会保持停止时的状态,因此请先删除它,否则它也会被跳过。 |
+| `--force-override` | 在创建某台虚拟机之前删除同名的虚拟机。如果该虚拟机正在运行,或者该文件夹不是虚拟机,则拒绝执行。 |
+
+## 另请参阅
+
+- [模板](templates.md)
+- [构建与查找模板](template-building.md)
+- [创建与运行虚拟机](../machines/create-and-run.md)
diff --git a/Documents/zh/storage/shader-cache.md b/Documents/zh/storage/shader-cache.md
new file mode 100644
index 00000000..1a861577
--- /dev/null
+++ b/Documents/zh/storage/shader-cache.md
@@ -0,0 +1,64 @@
+# 持久着色器缓存
+
+虚拟机会在多次启动之间保留已编译的 GPU 着色器,因此只有在最初几次运行、着色器正在编译时动画才会卡顿。要为现有虚拟机开启缓存或重置缓存,请参阅本页。
+
+使用 Standard 预设新建的虚拟机会自动启用 Task3 内核补丁和客户机 Metal 缓存复用。宿主机把缓存保存在 `<machine>/ShaderCache` 中,例如 `~/.vphone/machines/Lychee/ShaderCache`。可执行文件发生变化时,会获得新的宿主机缓存身份。
+
+## 为现有虚拟机开启
+
+安装包含此功能的 Core Bundle,并把已停止的虚拟机绑定到它。然后更新客户机环境和内核。两项更新都会保留客户机的数据;不需要重新恢复,也不需要 `fw patch`。
+
+### 在 Launchpad 中
+
+1. 在虚拟机的操作菜单中选择 **Update Guest Environment**(更新客户机环境)。
+2. 在它的 **Patches**(补丁)检查器中选择 **Update Kernel**(更新内核)。
+
+Standard 现在会自动选择 **GPU Task3 shader cache**。为单台虚拟机明确关闭的设置会被保留;如果之前取消勾选了该补丁,请先在编辑器中启用它。
+
+### 使用 Launchpad CLI
+
+```sh
+# Replace <version> with the installed Core Bundle version from bundle list.
+vphone-launchpad-cli vm stop Lychee
+vphone-launchpad-cli vm set-bundle Lychee <version> --update-environment
+vphone-launchpad-cli cfw update-kernel Lychee
+vphone-launchpad-cli vm start Lychee --wait
+```
+
+- `--update-environment` 重新部署客户机库和缓存复用标记。
+- `cfw update-kernel` 按当前的选择重新为 `FirmwareOriginals` 中的原始内核打补丁,并替换 Preboot 中的 kernelcache。
+
+只更改 Core Bundle 绑定不会更新已安装的内核。
+
+### 只用 vphone-cli
+
+在虚拟机关闭时,以 root 授权运行新 bundle 中的命令:
+
+```sh
+sudo vphone-cli cfw update-environment Lychee
+sudo vphone-cli cfw update-kernel Lychee
+```
+
+`vphone-cli fw patches Lychee` 会显示待应用的补丁。两条更新命令都会应用虚拟机当前的选择,包括其他待应用的客户机或内核更改。
+
+### 没有原始内核的旧虚拟机
+
+如果虚拟机的 `FirmwareOriginals` 中没有原始内核,需要先用新 bundle 运行 `fw prepare` 和 `fw patch`,让备用恢复目录包含更新后的内核。然后运行 `cfw update-kernel`。不要运行 `restore`。
+
+## 重置宿主机缓存
+
+停止虚拟机,然后删除它的 `ShaderCache` 目录。下次启动时会使用全新的宿主机缓存。
+
+客户机的 Metal 缓存是 `Disk.img` 中的独立文件,因此清除宿主机缓存不一定能重现首次运行时的全部卡顿。
+
+## 限制
+
+- Task3 只适用于 cloudOS 26.4 内核,在 tvOS 预设中处于停用状态。
+- 在早于 macOS 27 的宿主机上,客户机会协商使用宿主机自身支持的最高版本并保留该版本的功能,因此在这类宿主机上,宿主机缓存仅在单次启动内有效。
+- 运行时验证覆盖了 macOS 27.0.1、cloudOS 26.4,以及 iOS 27.0.1 和 26.6.2 客户机。较旧的宿主机只检查了其框架代码,未实际运行。
+
+## 另请参阅
+
+- [Core Bundle](../launchpad/core-bundles.md)
+- [Launchpad CLI](../launchpad/launchpad-cli.md)
+- [资料库、固件与备份](library-and-backups.md)
diff --git a/Documents/zh/storage/sharing-disk-space.md b/Documents/zh/storage/sharing-disk-space.md
new file mode 100644
index 00000000..e1b5de41
--- /dev/null
+++ b/Documents/zh/storage/sharing-disk-space.md
@@ -0,0 +1,50 @@
+# 在虚拟机之间共享磁盘空间
+
+`vm rebase` 让一台已停止的虚拟机与另一台虚拟机或模板共用相同的磁盘块,相同的数据只存储一份。对未使用模板恢复或通过导入得到的虚拟机使用它,可以收回磁盘空间。
+
+从同一个 IPSW 分别恢复的两台虚拟机在磁盘上不共享任何内容,尽管它们的磁盘映像大部分相同:两台 iOS 27.0 iPhone 在各自约 20 GB 的数据中,有大约 8.6 GB 位于相同位置的字节完全相同,主要是系统宗卷。
+
+## 变基虚拟机
+
+1. 停止两台虚拟机。它们必须位于同一个 APFS 宗卷上。
+2. 查看变基能节省多少空间:
+
+ ```sh
+ vphone-cli vm rebase second --onto first --dry-run
+ ```
+
+3. 变基到一台虚拟机或一个模板上:
+
+ ```sh
+ vphone-cli vm rebase second --onto first
+ vphone-cli vm rebase second --onto 3f2a91c0d4e7
+ ```
+
+`--onto` 接受虚拟机名称,或 `vm template list` 中的模板标识符(或其唯一前缀);名称同时匹配两者时,以虚拟机为准。`--dry-run` 只报告会共享和写入哪些内容,不写入任何数据。
+
+在旧映像释放之前,宗卷需要有足够的可用空间来存放写入的块。
+
+## 工作原理
+
+变基会以基准磁盘映像的 APFS 克隆为起点重建 `second` 的磁盘映像,只写入不同的块。替换映像之前,每个字节都会与原映像比对,因此客户机看到的磁盘完全一致。
+
+只有磁盘映像会改变:`SEPStorage`、`nvram.bin`、`config.plist` 和设备身份保持不变。变基到模板上不会改动模板,虚拟机也不会成为该模板的克隆:`vm template show` 不会列出它。
+
+## 理解结果
+
+节省的空间是 **newly shared**(新共享)的数值。相同且在磁盘上已经是同一批块的字节会报告为 **already shared**(已共享),对它们变基不会释放任何空间。
+
+`vm create` 从同一个模板创建的虚拟机已经共享该模板的块,因此把其中一台变基到另一台或该模板上,释放的空间很少。命令会在比对前提示这一点,节省量不足 0.1 GB 时也会再次提示。值得变基的是未使用模板恢复(`--no-template`)或导入的虚拟机。
+
+## 注意事项
+
+- 只有在没有其他东西持有旧映像的块时,空间才会真正收回。虚拟机的快照以及从它克隆出的虚拟机都会保留这些块;请先删除它们,否则不会节省空间。
+- `du` 和访达仍按完整大小计算每个映像。宗卷的可用空间(`df`)才是准确的衡量标准。
+- 任何一台虚拟机写入磁盘后,两个映像都会再次产生差异。从不启动的基准(例如模板)始终是最好的基准,以后再次变基即可收回产生差异的部分。
+- 被中断的变基不会改动虚拟机,但可能在其中留下一个隐藏的 `.rebase-*` 文件夹;请删除该文件夹。
+
+## 另请参阅
+
+- [模板](templates.md)
+- [快照](snapshots.md)
+- [资料库、固件与备份](library-and-backups.md)
diff --git a/Documents/zh/storage/snapshots.md b/Documents/zh/storage/snapshots.md
new file mode 100644
index 00000000..ca0d9ac0
--- /dev/null
+++ b/Documents/zh/storage/snapshots.md
@@ -0,0 +1,65 @@
+# 快照
+
+快照保存已停止虚拟机的磁盘和启动状态,以便日后还原到该状态。可以在全新安装后创建快照,在客户机中尝试有破坏性的操作,然后再还原。
+
+## 创建、列出、还原和删除
+
+1. 停止虚拟机:运行 `vphone-cli vm stop myphone`,或在其窗口中关闭它。
+2. 创建快照,然后在客户机中操作。想回到保存的状态时,再次停止虚拟机并还原快照。
+
+```sh
+vphone-cli vm snapshot create myphone clean --note "fresh install"
+vphone-cli vm snapshot list myphone
+vphone-cli vm snapshot revert myphone clean
+vphone-cli vm snapshot delete myphone clean
+```
+
+- `revert` 和 `delete` 在改动任何内容前都会询问;`--force` 跳过询问。
+- 还原后快照仍会保留,因此可以再次回到该快照。
+- `list --json` 打印一个由 `{"name", "created", "note"}` 对象组成的数组,按从旧到新排列,`created` 采用 ISO 8601 格式,没有备注时省略 `note`。
+- `list` 和 `delete` 可以在虚拟机运行时使用;两者都不会触及虚拟机正在使用的文件。
+
+## create 或 revert 被拒绝时
+
+虚拟机正在运行时,或者有任何进程打开了它的磁盘映像、`SEPStorage` 或 `nvram.bin` 时,`create` 和 `revert` 会拒绝执行。拒绝信息会列出持有这些文件的每个进程。如果这些进程都不是在运行虚拟机(例如备份工具或聚焦),信息中会说明这一点,等该进程关闭文件后重试即可成功。
+
+如果虚拟机不在 APFS 宗卷上,`create` 也会拒绝执行,而不是拷贝可能有几十 GB 的磁盘映像。
+
+如果快照的 `Snapshot.plist` 没有列出全部三个状态文件,或者列出了不属于快照的文件,就会在改动任何内容之前被判定为已损坏并拒绝使用。
+
+还原要么全部完成,要么完全不做。如果中途失败,它会把虚拟机自己的文件放回原处并报告错误,因此虚拟机保持原样。在极少数情况下,如果放回文件也失败了,错误信息会说明这一点:请在启动虚拟机之前再次还原到某个快照。
+
+## 快照包含的内容
+
+| 包含的内容 | 原因 |
+| --- | --- |
+| 磁盘映像(`Disk.img`) | 客户机的系统和数据 |
+| `SEPStorage`、`nvram.bin` | 安全隔区状态和启动链的 NVRAM,必须与磁盘匹配 |
+| `PatchReceipt.plist` | 客户机中实际生效的补丁 |
+| `restore-info.json` | 磁盘上的 iOS 版本,以及 `cfw install` 是否完成 |
+
+磁盘、`SEPStorage` 和 `nvram.bin` 总是一起变动。安全隔区的防重放计数器保存在 `SEPStorage` 中,磁盘保存与之匹配的状态;如果磁盘与 `SEPStorage` 来自不同时刻,SEP 会在下次启动时 panic。
+
+`PatchReceipt.plist` 和 `restore-info.json` 存在时会被保存。如果创建快照时其中某个文件不存在,还原时会删除它,从而让这些记录描述的是还原后的磁盘,而不是之后的某次安装。
+
+不包含在快照中、还原时也不会改变的内容:
+
+- `config.plist`:设备身份、CPU、内存、网络和其他设置。随时可以用 `vm config` 更改;还原快照不会撤销这些更改。
+- 补丁选择(`PatchSelection.plist`)、恢复目录、`FirmwareOriginals/` 和 ROM。这些是 Mac 上的输入,而不是客户机状态。
+- `launchpad.json`。Launchpad 会在快照文件夹中保存自己的副本,并自行放回。CLI 不会改动快照文件夹中的任何额外文件,并在删除快照时一并删除它们。
+
+## 磁盘空间
+
+快照以 APFS 克隆的形式保存在 `<vm>/Snapshots/<name>/` 中。创建快照是瞬间完成的,不占用空间:在客户机写入之前,虚拟机与它的快照共享所有块,写入之后也只有改动过的块占用新空间。`du` 和访达会按磁盘的完整大小计算每个快照,夸大了实际占用;宗卷的可用空间才是准确的衡量标准。
+
+快照会保留创建时的磁盘块。只要该虚拟机的快照仍持有旧块,`vm rebase` 就不会释放任何空间;见[在虚拟机之间共享磁盘空间](sharing-disk-space.md)。
+
+## 克隆、导出与重命名
+
+`vm clone` 和 `vm export` 不包含快照:克隆或导入的虚拟机一开始没有快照。删除或重命名虚拟机时,它的快照会一起删除或重命名。
+
+## 另请参阅
+
+- [资料库、固件与备份](library-and-backups.md)
+- [在虚拟机之间共享磁盘空间](sharing-disk-space.md)
+- [故障排查](../help/troubleshooting.md)
diff --git a/Documents/zh/storage/template-building.md b/Documents/zh/storage/template-building.md
new file mode 100644
index 00000000..076c093f
--- /dev/null
+++ b/Documents/zh/storage/template-building.md
@@ -0,0 +1,118 @@
+# 构建与查找模板
+
+如何手动把虚拟机制作成模板,如何查询 `vm create` 会使用哪个模板,以及 Launchpad 如何构建模板。模板是什么、它的键包括哪些内容,请先阅读[模板](templates.md)。
+
+## 把虚拟机制作成模板
+
+要在创建虚拟机后立即把它转换为模板,请依次停止、精简、进行设置启动,然后采纳。Launchpad 在需要构建模板时也是这样做的:
+
+```sh
+vphone-cli vm stop phone-src
+vphone-cli vm template trim phone-src --tier standard # offline, no root; frees nothing until the setup boot
+vphone-cli vm template setup phone-src # headless; --window to watch, slimming switches as for vm create
+vphone-cli vm template adopt phone-src --iphone-source … --cloudos-source … # key from its records; the sources are recorded
+vphone-cli vm create phone-d --template <id> --skip-first-boot
+```
+
+### vm template setup
+
+- 拒绝运行中的虚拟机和已冻结的模板。
+- 自身不做任何精简:它沿用 `vm template trim` 记录的级别,并拒绝指定了其他级别的 `--trim`。
+- 在虚拟机上运行时,如果有 vphoned 无法移除的 App,它会报告出来,并且不把该 App 写入记录的步骤中,这样采纳后的键反映的就是实际完成的操作。
+- `--strict` 会让它直接失败;此时不记录任何内容,可以再次运行设置启动。如果虚拟机之后要用 `--expect` 以 `vm template find` 针对相同开关给出的键采纳,请使用此选项。
+- 如果传入 `vm template list` 中的 `.building-…` 名称(设置启动失败的 `vm create`),它会按照该构建的键进行设置,从而确定精简方式;如果构建在离线精简之前就停止了,会先运行离线精简,成功后再冻结。
+
+### vm template adopt
+
+| 选项 | 作用 |
+| --- | --- |
+| `--iphone-source`、`--cloudos-source` | 像构建模板的 `vm create` 一样,把创建该虚拟机所用的 IPSW 记录到其 `Template.plist` 中。 |
+| `--json` | 像 `vm template show --json` 一样打印新模板。 |
+| `--expect <id>` | 除非虚拟机的记录得出的模板标识符为 `<id>`(即 `vm template find` 针对构建该虚拟机所用选项打印的 `id`),否则拒绝采纳,并保持虚拟机原样。 |
+
+只要之后还需要再次找到某个模板,就请使用 `--expect`。如果不使用,设置启动未完全达成(有无法移除的 App)的虚拟机会以另一个键保存,之后使用这些选项的每次 `vm create` 都找不到它,于是又会构建一个新模板。
+
+如果能推算出预期的键(库中有模板或构建具有该键,或者只有精简方式不同时可以推算),拒绝信息会列出不同的字段。否则会打印虚拟机自己的键供比较。使用 `--json` 时,拒绝信息也会打印到 stdout,命令以状态码 1 退出:
+
+```text
+{"adopted": false, "error": "unexpected_template", "id": …, "expected": …, "differences": […], …}
+```
+
+## 查找模板
+
+`vm template find` 可以回答使用相同选项的 `vm create` 会从哪个模板克隆,而不会下载、恢复或改动任何内容:
+
+```sh
+vphone-cli vm template find --iphone-source … --cloudos-source … [--device …] [--preset …] [--disk-size …] [--block <id>] [--allow <id>] [slimming switches] --json
+```
+
+它像 `vm create` 一样推算键。如果 IPSW 是本地文件或已在 IPSW 缓存中,构建版本从 IPSW 读取;否则从记录了相同两个来源的模板中获取,因此即使 IPSW(包括本地 IPSW)已被删除,键仍然可以解析。`--block` 和 `--allow` 是按 `fw set-patches` 记录方式表示的单个补丁覆盖设置。
+
+| JSON 字段 | 含义 |
+| --- | --- |
+| `resolved` | 能否推算出键 |
+| `resolvedBy` | `ipsw` 或 `template` |
+| `id` | 模板标识符 |
+| `summary` | 键摘要 |
+| `key` | 完整的键 |
+| `template` | 匹配的模板,格式与 `vm template show --json` 的输出相同,可能是当前的或过期的 |
+| `usable` | 模板存在且未过期 |
+| `building` | 有创建任务持有其构建锁 |
+| `reason` | 键无法解析时的原因 |
+
+## 在 Launchpad 中
+
+Launchpad 2.9 及更新版本默认从模板创建虚拟机。
+
+### New Machine
+
+New Machine(新建虚拟机)打开时是一个简短的页面:名称、来自固件目录的设备和 iOS 版本,以及一个 **Slim System**(精简系统)开关。下方有一行汇总其余设置,点击可打开 **Advanced Options**(高级选项),共四页:
+
+- 硬件;
+- 模板及其组成部分:精简级别和保留的语言、服务配置,以及要移除哪些系统 App;
+- Core Bundle、自定义 IPSW 和补丁;
+- 位置、网络和恢复选项。
+
+这一行会统计与默认值不同的设置数量,并指出其中阻止 **Create**(创建)的内容。关闭 **Create from a template**(从模板创建)后,会像 `--no-template` 一样单独恢复虚拟机,使用它自己的密钥,且不做精简。不提供 Apple 账户选项:无论如何客户机都会拒绝登录,因此只要服务配置为精简,Launchpad 就会传入 `--accounts-off`。表单会随页面内容增高,最高 600 点,超过后可以滚动,因此在笔记本电脑屏幕上按钮也始终可见。
+
+### 需要重建 kernelcache 的固件
+
+在 **Firmware**(固件)下,如果某个版本也能在它自己的 cloudOS 上运行(`fw catalog` 的第三列),就会在推荐的 cloudOS 旁边提供该 cloudOS。创建时会以你的身份准备 kernelcache 组合,再由辅助程序以 root 身份链接,这会请求一次授权。
+
+对于这些组合,Launchpad 仍会显示一个 `ipsw` 工具字段,供用它来准备组合的旧版兼容 Core Bundle(2.12.0)使用。Core Bundle 2.12.1 及更新版本会原生提取,并忽略所选的路径。
+
+iPhone XS Max 运行 iOS 18.1 到 18.7.2,每个版本都运行在各自版本的 cloudOS 上,不使用模板,默认使用 Minimal 预设;Standard 同样可用(已在 18.6 上验证)。它的组合总是需要重建 kernelcache,因此 **Firmware** 还会要求填写 macOS 构建机:
+
+- 一台运行 macOS 15 或 26.0 到 26.3、已打开“远程登录”的 Mac 或 macOS 虚拟机的 `user@host`;
+- 用于 ssh 和 sudo 的密码;如果使用 ssh 密钥且 sudo 无需密码,则留空。
+
+Launchpad 会保存构建机,但不保存密码,密码只通过环境变量(`VPHONE_KMUTIL_SSH_PASSWORD`)传给 `vphone-cli`。创建时会以你的身份通过 ssh 准备和链接组合。从 macOS 26.4 起必须指定构建机;在更早的 Mac 上如果没有指定,则由辅助程序以 root 身份链接组合。
+
+### 创建流程如何使用模板
+
+创建流程会先运行 `vm template find`。
+
+- 如果有未过期的模板匹配,就从它克隆虚拟机(`vm create --template <id> --skip-first-boot`)并启动。
+- 如果没有匹配的模板,就在同一个资料库中的一台临时虚拟机里构建模板,名称为 `template-` 加八位十六进制数字。它运行常规步骤(恢复,然后通过辅助程序执行 `cfw install`),接着运行 `vm template trim`、无界面的 `vm template setup --strict` 和 `vm template adopt --iphone-source … --cloudos-source … --expect <id>`,最后从结果中克隆虚拟机。
+
+如果应移除的 App 仍然存在,设置启动就会失败;如果构建的键与 `find` 算出的不同,采纳就会失败。因此,构建永远不会以之后的创建找不到的 id 保存。每一项都是独立的步骤,会显示各自的耗时,失败的步骤会显示 `vphone-cli` 给出的原因。
+
+New Machine 的 **Patch Settings**(补丁设置)中的单个补丁覆盖设置,按模板键的划分方式分为两类:
+
+- 启动链覆盖设置属于键:模板会带着它们构建,`find` 也会查找带有它们的模板。
+- 客户机补丁覆盖设置不属于键:模板构建时不包含它们。克隆之后,创建流程会用 `fw set-patches` 把它们记录到新虚拟机上,并在首次启动前通过辅助程序用 `cfw update-environment` 写入(即 **Apply guest patches** 步骤)。因此,模板永远不会把某次创建的客户机补丁选择带给另一次创建。
+
+构建好模板后,创建流程会询问是否删除构建它所用的两个 IPSW;未经确认不会删除任何内容。
+
+### 在 Launchpad 中管理模板
+
+- **File > Templates…** 列出每个资料库的模板及其虚拟机、精简方式、大小和状态,并可以删除它们。
+- **Guest System…**(位于虚拟机的 Actions 菜单和检查器中)可以切换运行中虚拟机的服务配置,并恢复模板移除的系统 App。
+- 检查器和虚拟机列表会在每台虚拟机文件分配的空间旁显示其独占的磁盘占用:即没有其他虚拟机或模板持有、删除该虚拟机就会释放的块。在此之前创建的本地时间机器快照会保留这些块,直到快照过期。
+
+## 另请参阅
+
+- [模板](templates.md)
+- [批量创建虚拟机](many-machines.md)
+- [固件准备](../firmware/firmware-preparation.md)
+- [Launchpad CLI](../launchpad/launchpad-cli.md)
diff --git a/Documents/zh/storage/templates.md b/Documents/zh/storage/templates.md
new file mode 100644
index 00000000..691fd9d2
--- /dev/null
+++ b/Documents/zh/storage/templates.md
@@ -0,0 +1,162 @@
+# 模板
+
+模板是一台完整且已冻结的虚拟机,`vm create` 从它克隆出新的虚拟机。使用某组选项第一次创建时会构建模板;之后使用相同选项的每次创建只需几秒钟,也不会下载任何内容。要控制模板的构建、精简和清理方式,请参阅本页。
+
+## 从模板创建虚拟机
+
+`vm create` 默认使用模板:
+
+```sh
+vphone-cli vm create phone-a --iphone-source … --cloudos-source … # builds the template, clones phone-a
+vphone-cli vm create phone-b --iphone-source … --cloudos-source … # clones phone-b, no restore
+vphone-cli vm create phone-c --template 3f2a91c0d4e7 --cpu 4 --memory 6144
+```
+
+- 有匹配的模板时,`vm create` 会以新身份从模板克隆虚拟机,为它设置所需的 CPU、内存和网络,并启动一次以检查 vphoned。这既不需要 root 权限,也不需要 IPSW。
+- 没有匹配的模板时,它会按需下载 IPSW,在暂存文件夹中运行完整流程,构建并冻结模板,然后从模板克隆虚拟机。
+- `--template <id>` 按标识符或至少四位的唯一前缀从模板克隆,不接受 IPSW 选项。如果指定了 `--device`、`--preset`、`--disk-size` 和精简开关,它们必须与模板一致;克隆无法更改这些设置。
+- `--no-template` 单独恢复虚拟机,使用它自己的密钥;不接受精简开关。
+
+要手动把虚拟机制作成模板、查询 `vm create` 会使用哪个模板,或者了解 Launchpad 如何构建模板,请参阅[构建与查找模板](template-building.md)。
+
+## 模板如何匹配
+
+在恢复任何内容之前,`vm create` 会根据选项和两个 IPSW 算出一个模板键。该键包括:
+
+- 客户机设备;
+- iOS 和 cloudOS 的版本及构建版本;
+- 补丁预设及其解析出的启动链补丁。对于 bundle 不自带的预设(预设文件,或 `~/.vphone/patches_presets` 中的预设),它解析出的每个补丁都会计入,包括客户机补丁,因为这类预设可能在标识符不变的情况下发生变化,而克隆会保留模板的客户机补丁;
+- bundle 系列(2.9.x 为 `2.9`);
+- 磁盘大小;
+- 从客户机 System 宗卷中精简掉的内容(`--trim`)以及保留的语言;
+- 下文的精简开关。
+
+CPU、内存、屏幕和网络不属于该键。
+
+如果 IPSW 是本地文件或已在 IPSW 缓存中,构建版本从 IPSW 读取。否则,会像 [`vm template find`](template-building.md) 那样,从记录了相同两个来源的模板中获取;已被删除的本地 IPSW 视为不存在。
+
+### 构建模板
+
+没有匹配的模板时,完整流程会在 `.templates/.building-<id>-<uuid>/` 中运行:`cfw install`、离线精简,然后是设置启动。结果会冻结,并一步重命名为 `<library>/.templates/<id>/`。
+
+- 无论 `--keep-artifacts` 如何设置,恢复目录都会在冻结前删除。它约有 11 GB,只要模板存在就会一直占用空间,而且任何克隆都用不上它。`--keep-artifacts` 只在使用 `--no-template` 时才会保留它;`vm template adopt` 也会删除它。
+- 使用相同键的第二个 `vm create` 会等待第一个完成,而不是再恢复一份副本。
+- 构建失败时,结果会保留在暂存文件夹中供检查。
+
+模板在构建过程中会为设置启动而启动一次,冻结后就再也不会启动。
+
+## 离线精简
+
+`cfw install` 之后,模板构建会在宿主机上装载客户机的 System 宗卷,离线删除其中客户机永远用不到的系统文件。`vm create` 的 `--trim`(默认 `standard`)和 `vm template trim` 的 `--tier` 用于选择精简级别:
+
+| 级别 | 删除的内容 | 约 |
+| --- | --- | --- |
+| `none` | 不删除 | |
+| `conservative` | `usr/standalone/update` 中的内容(软件更新 ramdisk、基带固件) | 0.35 GB |
+| `standard` | conservative 的内容,加上 AirPods/Beats 配对资源(`PreinstalledAssetsV2/RequiredByOs/com_apple_MobileAsset_SharingDeviceAssets`)、表盘(`NanoTimeKit/FaceBundles`),以及所有未保留语言的 `LinguisticData/RequiredAssets_*.bundle` | 1.2 GB |
+| `aggressive` | 保留:在客户机上验证之前会被拒绝 | |
+
+`--keep-languages`(默认 `en,zh-Hans,zh`;始终保留英语)选择 `standard` 保留哪些语言。级别、列表版本和保留的语言都属于模板键(`standard/1/en,zh,zh-Hans`),因此精简方式不同的模板永远不会匹配。
+
+> [!WARNING]
+> 精简无法撤销:克隆无法找回这些文件。
+
+删除的文件起初不会释放任何空间。客户机原始的系统快照(`orig-fs.disabled.rn-*`,由 `cfw install` 留下)仍持有所有块,而宿主机即使以 root 身份也无法删除它。设置启动的第一步就是删除它,之后空间才会归还。因此,不会进行设置启动的模板不能精简,而精简过的模板只有在其快照删除后才能冻结或采纳。
+
+`vm template trim` 不需要 root 权限。它可以在一台未从模板克隆、已停止的虚拟机上运行,也可以在未完成的 `.building-…` 文件夹上运行,但会拒绝已冻结的模板。
+
+## 设置启动与精简
+
+设置启动以每个克隆都应具备的初始状态完成模板。它启动模板一次,并通过 vphoned 依次执行:
+
+1. 删除 `cfw install` 留下的 `orig-fs.disabled.rn-*` APFS 快照(在删除之前,它占用约 20 MB,外加从 System 宗卷中精简掉的所有文件);
+2. 跳过设置助理(`setup.skip`);
+3. 等待首次启动的工作完成(`setup.settle`,最长 10 分钟):installd 会在首次启动时展开可移除的系统 App;
+4. 移除系统 App(`apps.remove_system`,备份保留在客户机中);
+5. 应用服务配置(`services.profile.apply`),其中包括关闭登录后续操作守护进程(`followupd`、`appleidsetupd`);
+6. 重启,然后检查:没有残留快照、设置已完成、配置中的服务都未运行、已移除的 App 不存在、vphoned 有响应;
+7. 清除 `vphone-vm` 在这次启动中固定的设备名称,然后正常关闭客户机。
+
+每一步都有时限。某一步失败时,虚拟机会停止,不记录任何内容,构建也不会被冻结;`vm create` 会指出是哪一步以及如何重试。
+
+| 开关 | 默认值 | 作用 |
+| --- | --- | --- |
+| `--slim on\|off` | on | `off` 不精简任何内容,保留所有 App 和服务。设置启动仍会运行:跳过设置并删除快照。 |
+| `--trim none\|conservative\|standard` | standard | 上文所述的离线精简。 |
+| `--keep-languages <list>` | `en,zh-Hans,zh` | `--trim standard` 保留的语言。 |
+| `--service-profile trimmed\|none` | trimmed | vphoned 的精简配置:关闭约 140 个 launchd 任务,其中包括 App Store 守护进程和登录后续操作。使用此配置的手机无法与 Apple Watch 配对(见 `Research/Guest/watch_pairing.md`)。 |
+| `--remove-apps on\|off` | on | 移除 App Store、“家庭”、Apple TV、Apple News、FaceTime 通话、iTunes Store、“信息”、“游戏”、“查找”和“钱包”。保留“相机”和“电话”。 |
+| `--keep-apps <ids>` | 无 | 要从上述列表中保留的 bundle ID,以逗号分隔(`com.apple.findmy,com.apple.Passbook`)。 |
+| `--accounts-off` | off | 同时关闭 `akd`、`amsaccountsd` 和 `appleaccountd`。之后客户机无法登录 Apple 账户。 |
+
+每个选择都属于模板键,因此精简方式不同的模板可以并存,并且各自只服务于请求该精简方式的创建。服务配置的限制见[手表配对记录](../../../Research/Guest/watch_pairing.md)。
+
+在克隆上,移除的 App 和服务配置仍可以撤销,方法是使用 `vphone-launchpad-cli guest rpc` 或 Launchpad 中的 **Guest System**:
+
+- `apps.restore_system` 从备份中恢复一个 App。
+- `services.profile.apply {"profile":"none"}` 重新开启配置所关闭的全部内容,不多也不少。
+
+### 克隆继承的内容
+
+克隆会从模板继承:已完成的设置、设置启动后的 App 和服务状态、installd 和索引程序在首次启动时完成的工作,以及那次启动时的 Data 宗卷。
+
+克隆不会继承设备名称。模板固定的名称已被清除,因此在克隆自己的虚拟机连接并固定克隆的名称之前,它显示为 `iPhone`。新身份还意味着 Mac 会再次询问“要信任此电脑吗?”。
+
+## 共享的密钥
+
+> [!WARNING]
+> 从同一个模板克隆出的每台虚拟机,都与模板以及彼此共享 SEP 根密钥、Data 宗卷密钥,以及恢复和设置启动写入的数据。理论上,一个克隆可以解密另一个克隆的 Data 宗卷。
+
+需要独立密钥的虚拟机(例如为多设备研究登录 Apple 服务)应使用 `--no-template` 创建。
+
+与 `vm clone --new-identity` 一样,克隆首次启动时会获得新的 ECID、UDID 和 MAC 地址。在 APFS 上,它们与模板共享所有未改动的块:新克隆在开始写入之前几乎不占用空间,而精简过的模板留给它的首次启动写入也很少。
+
+## 管理模板
+
+```sh
+vphone-cli vm template list # id, key summary, STALE with the reasons
+vphone-cli vm template show <id> --json
+vphone-cli vm template trim myphone --tier standard # trim a stopped VM before adopting it
+vphone-cli vm template setup myphone # the setup boot, on a stopped VM
+vphone-cli vm template adopt myphone # freeze a stopped, newly created VM into a template
+vphone-cli vm template delete <id>
+```
+
+### 过期的模板
+
+当这个 `vphone-cli` 属于另一个 bundle 系列、模板的键格式较旧、它的预设现在解析出不同的启动链补丁,或者它的补丁回执与计划不一致时,模板会被列为过期(stale)。过期的模板永远不会被使用:使用其键的 `vm create` 会失败并指出该模板。删除它,下一次 `vm create` 就会构建新的模板。
+
+### 采纳虚拟机
+
+`vm template adopt <vm>` 把一台已停止的虚拟机转换为模板,使用的键来自它自己的记录:`restore-info.json`、`PatchPlan.plist`、`config.plist`、磁盘映像、Launchpad 的 `launchpad.json`,以及 `vm template trim` 和 `vm template setup` 记录在其 `Template.plist` 中的步骤。该虚拟机会从 `vm list` 中消失。
+
+请在设置启动之后立即采纳虚拟机:每个克隆都会继承客户机在那之后所做的一切。有快照的虚拟机会被拒绝;会成为过期模板的虚拟机也会被拒绝,除非指定 `--force`。
+
+### 已冻结的模板永远不会启动
+
+`vm launch` 和 `vphone-vm` 会拒绝已冻结的模板,DFU 模式也一样。任何虚拟机名称都无法指向 `.templates` 中的内容,因此 `vm launch`、`clone`、`export`、`rename` 和 `delete` 不会意外选中模板。冻结后又启动过的模板会把状态写入之后每个克隆都会继承的块中,而此前创建的克隆将不再与它共享这些块。
+
+### 使用模板的虚拟机
+
+从模板克隆的虚拟机会在 `TemplateSource.plist` 中记录该模板。对它执行 `vm clone` 会保留该记录(副本同样共享模板的块),`vm export` 则不包含它(导入的虚拟机不共享任何内容)。该记录还注明了模板的构建,因此用相同键删除并重新构建的模板不会把从旧模板克隆出的虚拟机计算在内,因为它们不共享新模板的任何块。
+
+`vm template list` 和 `show` 会列出使用每个模板的虚拟机及其磁盘占用,`vm info` 会显示虚拟机所用的模板。当 `vm delete` 删除了从某个仍存在的模板克隆出的最后一台虚拟机时,会给出提示,但绝不会删除模板本身:
+
+```text
+note: template 3f2a91c0d4e7 (~17.40 GB) is no longer used by any machine; remove it with `vphone-cli vm template delete 3f2a91c0d4e7`
+```
+
+### 删除模板
+
+`vm template delete <id>` 删除模板;从它克隆出的虚拟机仍可正常使用。它们与模板仍共享的块只有在这些虚拟机改动它们或被删除时才会释放,因此只要克隆还在,删除模板释放的空间就小于模板的大小。
+
+它打印的提示会说明属于哪种情况:要么列出使用该模板的虚拟机(它们共享的块在被改动或虚拟机被删除前一直占用),要么说明当前没有虚拟机使用它,因此删除会释放其块。模板存在期间创建的本地时间机器快照可能会保留这些块,直到快照过期。`--json` 配合 `--force` 会打印同样的信息。
+
+模板会占用磁盘空间,尽管 `vm list` 不显示它们。请查看 `~/.vphone/machines/.templates`,并注意 `du` 会把模板及其每个克隆都按完整大小计算。
+
+## 另请参阅
+
+- [构建与查找模板](template-building.md)
+- [批量创建虚拟机](many-machines.md)
+- [在虚拟机之间共享磁盘空间](sharing-disk-space.md)
+- [资料库、固件与备份](library-and-backups.md)
diff --git a/README.md b/README.md
index 02618040..74988c6b 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-<div align="right"><a href="Documents/README.md">Docs</a> · <strong>English</strong> · <a href="Documents/README_zh.md">中文</a> · <a href="Documents/README_ja.md">日本語</a> · <a href="Documents/README_ko.md">한국어</a></div>
+<div align="right"><a href="https://lakr233.github.io/vphone-cli/">Docs</a> · <strong>English</strong> · <a href="https://lakr233.github.io/vphone-cli/zh/">中文</a> · <a href="https://lakr233.github.io/vphone-cli/ja/">日本語</a> · <a href="https://lakr233.github.io/vphone-cli/ko/">한국어</a></div>
# vphone-cli
@@ -11,38 +11,17 @@ Run a virtual iPhone on an Apple Silicon Mac.
vphone-cli runs iOS with Apple's Virtualization.framework and PCC research virtual machines, for security research, reverse engineering, and debugging.
-- **Graphical Window:** Use the virtual iPhone's screen on your Mac, browse apps and files, and take screenshots and screen recordings.
-- **Custom Firmware:** The system comes pre-patched, and you can install a package environment.
-- **Backup and Cloning:** You can export, import, and clone VMs.
-- **Automation API:** An optional local HTTP and WebSocket interface.
-- **No Extra Dependencies:** Needs no Xcode, Python, or Homebrew at runtime.
-
-## Requirements
-
-- A physical Apple Silicon Mac running macOS 15 or newer. It does not work in a macOS VM.
-- Free disk space. Each VM has a 64 GB virtual disk by default, and firmware takes more.
-- A network connection. Restoring the system fetches signing tickets online.
-- Adjusted security settings. Boot into macOS Recovery, run these commands in Terminal, then restart:
-
- ```sh
- csrutil enable --without debug
- csrutil allow-research-guests enable
- ```
-
- SIP stays enabled, with only the debugging restrictions relaxed. For details, see [Host Setup](Documents/Guides/host-setup.md).
-
-## Get Started
+## Documentation
-1. Download `vphone-launchpad-<version>-notarized.zip` from the [latest release](https://github.com/Lakr233/vphone-cli/releases/latest), unzip it, and open it. Not every release is notarized. If the latest one has no `-notarized` file, pick a notarized version from [Downloads](Documents/Downloads/README.md).
-2. In **Host Setup**, grant Developer Tools access and install the helper.
-3. In **Core Bundle**, click **Download and Install**.
-4. In **Machines**, click **New Machine**, choose a firmware pairing, and click **Create**.
+Everything else lives on the documentation site: **<https://lakr233.github.io/vphone-cli/>**
-Launchpad downloads the firmware, patches it, restores the system, and boots the VM. To use your own iPhone and cloudOS IPSWs, see [Compatibility](Documents/Guides/compatibility.md).
+- [Quick Start](https://lakr233.github.io/vphone-cli/get-started/quick-start): requirements, host settings, and your first VM with Launchpad.
+- [Manual](https://lakr233.github.io/vphone-cli/get-started/overview): machines, firmware, storage, networking, and troubleshooting, in English, 中文, 日本語 and 한국어.
+- [Research Notes](https://lakr233.github.io/vphone-cli/research/): patches, boot chain, restore, and the automation API reference.
-To install a package manager in the VM, see [Package Environment](Documents/Guides/package-environment.md).
+The sources of the site are in [`Documents/`](Documents/) and [`Research/`](Research/).
-### Let an agent do it
+## Let an Agent Install 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.
@@ -58,61 +37,11 @@ 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:
-
-```sh
-vphone-cli vm list
-vphone-cli vm launch myphone
-vphone-cli vm export myphone --out myphone.tzst
-```
-
-VMs are stored in `~/.vphone/`. Run `vphone-cli <group> --help` to see all commands. To create a VM without Launchpad, see [Create and Run](Documents/Guides/create-and-run.md).
-
-To turn on the automation API, add `--api-listen 127.0.0.1:8765` at launch and use the token it prints. See the [API documentation](Research/vphoned_http_api.md).
-
-## Boot ROMs
-
-New VMs start from two open-source ROMs instead of the closed ones in Virtualization.framework:
-
-- [OpenAVB](https://github.com/owngoal-dev/OpenAVB) replaces AVPBooter, the boot ROM. It needs no patch, so `fw patch` leaves it alone.
-- [OpenSEP](https://github.com/owngoal-dev/OpenSEP) replaces AVPSEPBooter, the SEP boot ROM.
-
-With both, nothing Apple wrote runs before iBoot and SEPOS. Both ship in `VPhone.bundle`, prebuilt from pinned upstream commits. Each one's README ([OpenAVB](VPhoneExecutable/VPhoneVirtualization/Resources/OpenAVB/README.md), [OpenSEP](VPhoneExecutable/VPhoneVirtualization/Resources/OpenSEP/README.md)) says how to rebuild it and check it byte for byte.
-
-VMs created by earlier versions keep Apple's ROMs. A VM switches either way without a restore, from its next start:
-
-```sh
-vphone-cli vm config myphone --rom openavb --seprom opensep # open-source ROMs
-vphone-cli vm config myphone --rom apple --seprom apple # Apple's ROMs
-```
-
-`vphone-cli vm info myphone` shows which ROMs a VM uses. Restoring a VM that boots OpenAVB needs `VPhone.bundle` 2.10.1 or newer. For the details, see [OpenAVB](Research/Firmware/openavb_boot_rom.md) and [OpenSEP](Research/Firmware/opensep_sep_rom.md) in the research notes.
-
-## Documentation
-
-| Document | Contents |
-| --- | --- |
-| [Downloads](Documents/Downloads/README.md) | Notarized Launchpad versions and matching `VPhone.bundle` versions |
-| [Host Setup](Documents/Guides/host-setup.md) | SIP and AMFI settings, building from source, environment checks |
-| [Create and Run](Documents/Guides/create-and-run.md) | The creation process, starting and stopping a VM |
-| [Templates](Documents/Guides/templates.md) | Reusing one restore for many VMs, slimming the guest |
-| [Library and Backups](Documents/Guides/library-and-backups.md) | Where VMs live, clones and exports |
-| [Snapshots](Documents/Guides/snapshots.md) | Save a stopped VM's disk state and revert to it |
-| [Compatibility](Documents/Guides/compatibility.md) | Verified firmware pairings |
-| [iPadOS Guests](Documents/Guides/ipados.md) | Run iPadOS instead of iOS |
-| [Other iPhone Models](Documents/Guides/iphone-models.md) | Run iOS from another iPhone model's IPSW |
-| [Package Environment](Documents/Guides/package-environment.md) | Installing and removing a package manager in the VM |
-| [Troubleshooting](Documents/Guides/troubleshooting.md) | Common errors and how to fix them |
-| [Networking](Documents/Guides/networking.md) | Network modes, addresses, port forwarding, and `tunnel` for a Mac behind a VPN or proxy |
-| [Launchpad Command Line](Documents/Guides/launchpad-cli.md) | Install and test a local build with `vphone-launchpad-cli` |
-| [All Guides](Documents/README.md) | Every guide, grouped by subject |
-| [Contributing](Documents/README.md#for-contributors) | Project structure, building from source, research notes |
-
-If these do not solve your problem, [open an issue](https://github.com/Lakr233/vphone-cli/issues).
-
## Acknowledgements
- [wh1te4ever/super-tart-vphone-writeup](https://github.com/wh1te4ever/super-tart-vphone-writeup)
- [owngoal-dev/OpenAVB](https://github.com/owngoal-dev/OpenAVB) and [owngoal-dev/OpenSEP](https://github.com/owngoal-dev/OpenSEP), the boot ROMs new VMs start from
+
+## License
+
+vphone-cli is released under the [MIT License](LICENSE).
diff --git a/Research/0_binary_patch_comparison.md b/Research/0_binary_patch_comparison.md
index e9871ff4..98f60b9e 100644
--- a/Research/0_binary_patch_comparison.md
+++ b/Research/0_binary_patch_comparison.md
@@ -1161,7 +1161,7 @@
> struct (`oBbtJ8x+s1q0OkaiocPuog`, `{1488, 2266, 326, 3.0f}`) does not change
> the live scale. Emitted only for an iPad guest.
>
-> See `Documents/Guides/ipados.md`.
+> See `Documents/en/firmware/ipados.md`.
>
> **Other iPhone models (2026-10-05, issue #576):** the four
> `devicetree-cfw-ipad_*` presentation patches and `devicetree-cfw-ipad_audio`
@@ -1179,7 +1179,7 @@
> (23G90) with cloudOS 26.4 (23E5207q): installed tree `model` iPhone18,1,
> artwork subtype 2622 at 3x, `/product/audio` acoustic ID 8021 from the board;
> the guest booted to the home screen at 402x874 points. See
-> `Documents/Guides/iphone-models.md`.
+> `Documents/en/firmware/iphone-models.md`.
>
> **Only the camera remains of EXP by default (2026-09-28).** `standard` is now the
> JB baseline plus the virtual camera. Off by default, besides the concealment
@@ -4361,7 +4361,7 @@ in VM selections, plans and receipts, including explicit opt-outs. New template
keys include the enabled kernel patch, so a pre-Task3 template cannot satisfy
the new Standard plan. Existing VMs bind the new bundle and run
`cfw update-environment` and `cfw update-kernel` while stopped, keeping data.
-See `Documents/Guides/shader-cache.md` and the Standard promotion section in
+See `Documents/en/storage/shader-cache.md` and the Standard promotion section in
`Guest/gpu_acceleration.md`. The previous opt-in notes describe development
validation; older host compatibility remains untested.
Promotion validation: 62 focused tests passed, as did the full `VPhone` bundle
diff --git a/Research/Firmware/tvos_support.md b/Research/Firmware/tvos_support.md
index 5fa48ab7..a5a8ee3a 100644
--- a/Research/Firmware/tvos_support.md
+++ b/Research/Firmware/tvos_support.md
@@ -348,7 +348,7 @@ through vphoned.
## Reproducing the validated configuration
Use the built bundle's `vphone-cli` on a host configured according to
-[host setup](../../Documents/Guides/host-setup.md). Both IPSWs must be supplied
+[host setup](../../Documents/en/get-started/host-setup.md). Both IPSWs must be supplied
locally: a donor above and cloudOS 23E5207q. Other pairings are unvalidated.
The VM and the installer's temporary directory must share an APFS volume;
TV guest updates refuse an in-place fallback when cloning is unavailable.
diff --git a/Research/Guest/gpu_acceleration.md b/Research/Guest/gpu_acceleration.md
index 15f3c2a0..9f0e7546 100644
--- a/Research/Guest/gpu_acceleration.md
+++ b/Research/Guest/gpu_acceleration.md
@@ -828,7 +828,7 @@ patch is part of the template's boot-chain digest, so a template lacking Task3
does not satisfy the new Standard key. Existing machines need their new Core
Bundle bound, `cfw update-environment`, then `cfw update-kernel` while stopped.
Launchpad exposes both updates through its helper. No restore or data erasure
-is involved. See `Documents/Guides/shader-cache.md` for the user workflow.
+is involved. See `Documents/en/storage/shader-cache.md` for the user workflow.
This changes preset selection and record naming only; the four kernel writes
and runtime coverage above are unchanged. The direct kernel patcher default
diff --git a/Research/Guest/ios16_bringup.md b/Research/Guest/ios16_bringup.md
index c66c5494..a72a2613 100644
--- a/Research/Guest/ios16_bringup.md
+++ b/Research/Guest/ios16_bringup.md
@@ -44,7 +44,7 @@ absent on 20G81 and otherwise aborts the grouped launchd patch before hook load.
Pass these selections to `vm create` or `fw set-patches`; the latter replaces
its entire override record, so retain every required allow when changing it.
Use Launchpad's CLI and a complete locally built `VPhone.bundle`, not a detached
-copy of the host executable. See `Documents/Guides/launchpad-cli.md` for installing
+copy of the host executable. See `Documents/en/launchpad/launchpad-cli.md` for installing
that bundle and binding a machine without changing other machines' versions.
Boot-chain changes require firmware preparation/patching and restore. The
diff --git a/Research/Guest/mac_name_resolution.md b/Research/Guest/mac_name_resolution.md
index 67ed38dc..87f68237 100644
--- a/Research/Guest/mac_name_resolution.md
+++ b/Research/Guest/mac_name_resolution.md
@@ -2,7 +2,7 @@
A guest process doing a plain BSD `connect("<mac>.local")` hung. What the
guest's resolver returned, and what vphoned now does about it. User-facing
-behaviour is in `Documents/Guides/networking.md`.
+behaviour is in `Documents/en/networking/overview.md`.
Measured 2026-10-03 with vphoned's `network.resolve` and a temporary in-guest
probe (register a record, then `getaddrinfo(AF_INET)` every 20 ms) on a macOS
diff --git a/Research/Guest/virtual_gyroscope.md b/Research/Guest/virtual_gyroscope.md
index dd780fbd..aaedb247 100644
--- a/Research/Guest/virtual_gyroscope.md
+++ b/Research/Guest/virtual_gyroscope.md
@@ -98,7 +98,7 @@ not restart backboardd, which would interrupt the guest UI.
To test a local build, install it with `vphone-launchpad-cli bundle install-local`
and bind the stopped test machine using `vm set-bundle <name> <version>
---update-environment`, as described in `Documents/Guides/launchpad-cli.md`.
+--update-environment`, as described in `Documents/en/launchpad/launchpad-cli.md`.
The mounted update adds this newly selected patch to an older machine too.
Reboot before testing. To turn it off, use the patch editor to block
`system-backboardd-cfw-gyroscope`, update the stopped machine's environment,
diff --git a/Research/History/manifest_and_refactoring_summary.md b/Research/History/manifest_and_refactoring_summary.md
index bf8bd75e..ced96ccf 100644
--- a/Research/History/manifest_and_refactoring_summary.md
+++ b/Research/History/manifest_and_refactoring_summary.md
@@ -2,7 +2,7 @@
> **Historical snapshot.** This document describes the earlier shell/Python
> manifest implementation. Those commands and files have since been replaced
-> by the native Swift workflow. See the [current VM guide](../../Documents/Guides/create-and-run.md)
+> by the native Swift workflow. See the [current VM guide](../../Documents/en/machines/create-and-run.md)
> and [research index](../README.md).
## Summary
diff --git a/Research/Host/disk_rebase.md b/Research/Host/disk_rebase.md
index 62cc0078..a46626cb 100644
--- a/Research/Host/disk_rebase.md
+++ b/Research/Host/disk_rebase.md
@@ -4,7 +4,7 @@ Why two machines restored from one IPSW share nothing on disk, how
`vm rebase` makes them share what is identical, and what was measured. The
implementation is `VPhoneDiskRebase` in
`VPhoneKit/VPhoneCoreKit/Bundle/VPhoneDiskRebase.swift`; user-facing
-behaviour is in `Documents/Guides/create-and-run.md` ("Sharing disk space
+behaviour is in `Documents/en/machines/create-and-run.md` ("Sharing disk space
between VMs").
## The problem
diff --git a/Research/Host/machine_identity_and_clone.md b/Research/Host/machine_identity_and_clone.md
index adbc26d2..a2072e9e 100644
--- a/Research/Host/machine_identity_and_clone.md
+++ b/Research/Host/machine_identity_and_clone.md
@@ -4,7 +4,7 @@ Where a machine's device identity lives, what `vm clone --new-identity`
changes, and why it changes nothing else. The implementation is
`VPhoneBundleOperations.clone` and `resetIdentity` in
`VPhoneKit/VPhoneCoreKit/Bundle/VPhoneBundleOperations.swift`; user-facing
-behaviour is in `Documents/Guides/create-and-run.md`.
+behaviour is in `Documents/en/machines/create-and-run.md`.
Tested on 2026-10-06 from one stopped source machine (iPhone17,3 guest, iOS
27.0 24A435 with cloudOS 26.4 23E5207q, bundle 2.6.0, standard preset), cloned
diff --git a/Research/Host/machine_templates.md b/Research/Host/machine_templates.md
index 205e0ab2..614eed33 100644
--- a/Research/Host/machine_templates.md
+++ b/Research/Host/machine_templates.md
@@ -6,7 +6,7 @@ from it with `clonefile(2)` and a new identity (see
[machine identity and clone](machine_identity_and_clone.md)), so a second
machine for the same firmware costs a clone and a few hundred MB of first-boot
writes instead of a 20 GB restore. User-facing behavior is in
-[Create and run](../../Documents/Guides/templates.md). What
+[Create and run](../../Documents/en/storage/templates.md). What
templates save against the alternatives that were measured, and the build and
clone timings, are in [disk space](disk_space.md).
diff --git a/Research/Host/network_fixed_address.md b/Research/Host/network_fixed_address.md
index bdec1ac0..f438d31e 100644
--- a/Research/Host/network_fixed_address.md
+++ b/Research/Host/network_fixed_address.md
@@ -3,7 +3,7 @@
What was tried on a real guest before settling the design in
`VPhoneKit/VPhoneCoreKit/Support/VPhoneNetworking.swift`, and why some of it
was taken out again. User-facing behaviour is in
-`Documents/Guides/networking.md`.
+`Documents/en/networking/overview.md`.
Tested on 2026-10-02: macOS 27.0.1 (26A434) host, `pcc-research-01` guest
(iOS 27.0, 24A435, cloudOS 26.4), launched headless from a local bundle.
diff --git a/Research/KernelCustomFirmwarePatches/README.md b/Research/KernelCustomFirmwarePatches/README.md
index 112f75e6..9d407bfb 100644
--- a/Research/KernelCustomFirmwarePatches/README.md
+++ b/Research/KernelCustomFirmwarePatches/README.md
@@ -13,4 +13,4 @@ These notes explain the source anchors, binary matches and validation evidence f
| Process and syscall paths | [proc PID info](patch_proc_pidinfo.md), [syscall mask](patch_syscallmask_apply_to_proc.md), [kcall10](patch_kcall10.md) |
| Follow-up evidence | [26.5 hook fixes](26.5_jb_hook_fixes.md), [post-validation additions](patch_post_validation_additional.md), [runtime verification archive](RuntimeVerification/README.md) |
-For the supported firmware flow, use `vphone-cli fw patch` or `vphone-cli vm create`; see the [user guide](../../Documents/Guides/create-and-run.md).
+For the supported firmware flow, use `vphone-cli fw patch` or `vphone-cli vm create`; see the [user guide](../../Documents/en/machines/create-and-run.md).
diff --git a/Research/KernelCustomFirmwarePatches/RuntimeVerification/README.md b/Research/KernelCustomFirmwarePatches/RuntimeVerification/README.md
index 354d51cd..38d597d1 100644
--- a/Research/KernelCustomFirmwarePatches/RuntimeVerification/README.md
+++ b/Research/KernelCustomFirmwarePatches/RuntimeVerification/README.md
@@ -3,7 +3,7 @@
> **Archived research procedure.** The commands and local file paths below
> describe the 2026-03-05 investigation and may not exist in the current
> checkout. For the current JB flow, see the
-> [VM guide](../../../Documents/Guides/create-and-run.md) and
+> [VM guide](../../../Documents/en/machines/create-and-run.md) and
> [patch notes index](../README.md).
This folder contains runtime + IDA verification artifacts for jailbreak kernel patches.
diff --git a/Research/README.md b/Research/README.md
index 0d42b68b..53e8b2ac 100644
--- a/Research/README.md
+++ b/Research/README.md
@@ -1,8 +1,28 @@
# Research library
-[Project overview](../README.md) · [User documentation](../Documents/README.md)
+[Project overview](../README.md) · [User documentation](../Documents/en/README.md)
-This directory keeps the evidence behind firmware patches, restore and the self-contained host runtime. **The current public workflow is JB only.** Many notes record earlier experiments and command names; use the [user guides](../Documents/README.md) and `vphone-cli --help` for current instructions.
+This directory keeps the evidence behind firmware patches, restore and the self-contained host runtime. **The current public workflow is JB only.** Many notes record earlier experiments and command names; use the [user guides](../Documents/en/README.md) and `vphone-cli --help` for current instructions.
+
+## Working on vphone
+
+- `vphone-launchpad`: a Mac app that downloads and installs `VPhone.bundle` and sets up the host. Released separately.
+- `vphone-cli`: prepares firmware, patches it, restores the system, and manages VMs.
+- `vphone-vm`: runs the VM and shows its window.
+- `vphoned`: the control service inside the VM. The window's features and the API work through it.
+
+| Path | Contents |
+| --- | --- |
+| [`VPhoneExecutable/`](../VPhoneExecutable/) | `vphone-cli`, `vphone-vm`, firmware patching and restore |
+| [`VPhoneKit/`](../VPhoneKit/) | Shared host libraries and API client |
+| [`VPhoneDaemon/`](../VPhoneDaemon/) | `vphoned` |
+| [`VPhoneGuestComponents/`](../VPhoneGuestComponents/) | Hooks and helper programs inside the VM |
+| [`VPhoneLaunchpad/`](../VPhoneLaunchpad/) | The Launchpad app and its helper |
+| [`VPhoneWebsite/`](../VPhoneWebsite/) | This documentation site, built with Rspress from `Documents/` and `Research/` |
+
+- `xcodebuild -workspace VPhone.xcworkspace -scheme VPhone build` produces and validates `VPhone.bundle`. Run each project's test scheme separately.
+- The user manual is `Documents/<lang>/`, one identical tree per language (`en` is the source). Every manual page is listed in its language's `README.md`; the site's sidebar is built from those tables. Research notes stay in English.
+- Preview the site with `npm ci && npm run dev` in `VPhoneWebsite/`.
## Start here
diff --git a/Skills/vphone-guest-control/evals/evals.json b/Skills/vphone-guest-control/evals/evals.json
index c1a511c3..d7c70100 100644
--- a/Skills/vphone-guest-control/evals/evals.json
+++ b/Skills/vphone-guest-control/evals/evals.json
@@ -16,7 +16,7 @@
{
"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.",
+ "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/en/help/troubleshooting.md; does not vm create to reproduce; stops and reports rather than changing host settings.",
"files": []
},
{
diff --git a/Skills/vphone-guest-control/references/finding-docs.md b/Skills/vphone-guest-control/references/finding-docs.md
index 63caf94c..d4f68194 100644
--- a/Skills/vphone-guest-control/references/finding-docs.md
+++ b/Skills/vphone-guest-control/references/finding-docs.md
@@ -4,7 +4,8 @@ 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/`).
+at <https://github.com/Lakr233/vphone-cli> (`Documents/`, `Research/`), or on the documentation site
+<https://lakr233.github.io/vphone-cli/>.
Order of preference: **the user guides** (current instructions) first, then
**`Research/`** (evidence and history, may mention retired commands), then the
@@ -24,13 +25,13 @@ note's command lines.
| 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/firmware-preparation.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` |
+| `vphone-vm` killed before a window opens; AMFI; "Research Guests" | `Documents/en/get-started/host-setup.md`, `Documents/en/help/troubleshooting.md`, `Research/Host/macos27_m6_amfi.md` |
+| Launchpad/bundle version mismatch, which Launchpad is notarized | `Documents/en/get-started/downloads.md`, `Documents/en/launchpad/bundle-integration.md` |
+| `vm create` failed at a step; restore or DFU trouble | `Documents/en/machines/create-and-run.md`, `Documents/en/firmware/firmware-preparation.md`, `Documents/en/firmware/compatibility.md`, `Research/Restore/native_restore_architecture.md`, `Research/Restore/virtual_dfu_probe.md` |
+| Which iPhone IPSW pairs with which cloudOS | `Documents/en/firmware/compatibility.md`; `vphone-cli fw catalog` (via `exec`) for what exists now |
+| Guest boots to a black screen or loops | `Documents/en/help/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/en/help/troubleshooting.md`, `Research/KernelCustomFirmwarePatches/README.md` |
+| No package manager, no ssh, bootstrap install | `Documents/en/machines/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") |
@@ -44,17 +45,20 @@ note's command lines.
| 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; Core Bundles and local builds | `Documents/Guides/launchpad-cli.md`, `Documents/Guides/core-bundles.md` |
+| Which binary does what in the bundle | `Research/Host/host_binary_split.md`, `Documents/en/launchpad/bundle-integration.md` |
+| Launchpad command line; Core Bundles and local builds | `Documents/en/launchpad/launchpad-cli.md`, `Documents/en/launchpad/core-bundles.md` |
## By subject
-- **User guides** (`Documents/Guides/`): `host-setup`, `create-and-run`,
- `firmware-preparation`, `templates`, `template-building`, `many-machines`,
- `library-and-backups`, `sharing-disk-space`, `snapshots`, `networking` and
- its `network-*` pages, `compatibility`, `troubleshooting`,
- `package-environment`, `bundle-integration`, `launchpad-cli`,
- `core-bundles`. `Documents/README.md` indexes them.
+- **User manual** (`Documents/en/`, also at <https://lakr233.github.io/vphone-cli/>):
+ `get-started/` (overview, quick-start, host-setup, downloads), `machines/`
+ (create-and-run, boot-roms, automation-api, device-name-and-clock,
+ package-environment), `firmware/` (compatibility, firmware-preparation,
+ iphone-models, ipados), `storage/` (library-and-backups, snapshots,
+ templates, template-building, sharing-disk-space, many-machines,
+ shader-cache), `networking/`, `launchpad/` (launchpad-cli, core-bundles,
+ bundle-integration) and `help/troubleshooting`. `Documents/en/README.md`
+ indexes them; `zh/`, `ja/` and `ko/` are translations of the same tree.
- **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
diff --git a/Skills/vphone-guest-control/references/install-faq.md b/Skills/vphone-guest-control/references/install-faq.md
index 47a26eba..7d7105cd 100644
--- a/Skills/vphone-guest-control/references/install-faq.md
+++ b/Skills/vphone-guest-control/references/install-faq.md
@@ -19,7 +19,7 @@ symptom, apply the fix, and say which issue it was. Issue numbers are for
**"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`.
+2.2.1 are not notarized; the current list is in `Documents/en/get-started/downloads.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
@@ -52,7 +52,7 @@ user on an ad hoc build must reset after every switch. `status` →
| --- | --- |
| `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 |
+| `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/en/get-started/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 |
@@ -68,7 +68,7 @@ user on an ad hoc build must reset after every switch. `status` →
## 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`).
+ series. Stay in the same series (`Documents/en/get-started/downloads.md`).
- Launchpad never updates itself; the user replaces the app.
- A rebuilt local bundle needs `install-local` again (new signature). It
installs as a new `<version>-local.<hash>` beside the old build; machines stay
@@ -94,11 +94,11 @@ user on an ad hoc build must reset after every switch. `status` →
| Irisin cannot install `openssh` (#528) | `launchctl` (and the other base packages) were missing. Install `owngoal-bootstrap-vphone` from OwnGoal Packages with Bootstrap Install ([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` |
+| An app is killed by `EXC_GUARD` (#291) | `Documents/en/help/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
+questions. Read `Documents/en/firmware/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
index 511db72f..ebe7b1b8 100644
--- a/Skills/vphone-guest-control/references/install.md
+++ b/Skills/vphone-guest-control/references/install.md
@@ -21,7 +21,7 @@ already shows as done. Steps 1 and 2 happen once per Mac, by the Mac's owner.
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.
+ `Documents/en/get-started/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
@@ -45,7 +45,7 @@ Recovery and are the owner's call. Say which check failed and stop.
Launchpad checks it again when it comes to the front, without a relaunch.
`canInstallBundles` in `status` turns `true` when both are done.
-Which versions are notarized is listed in `Documents/Downloads/README.md`.
+Which versions are notarized is listed in `Documents/en/get-started/downloads.md`.
## The CLI on PATH
@@ -118,7 +118,7 @@ paths are resolved by the CLI. Installing does not move existing machines: bind
one with `vm set-bundle <name> <version> --update-environment`, or create one
with `vm create <name> --bundle <version>`. Each rebuild installs as a new
version; remove old ones no machine uses. To compare two builds, see
-`Documents/Guides/core-bundles.md` (Comparing two builds).
+`Documents/en/launchpad/core-bundles.md` (Comparing two builds).
## When an install step fails
diff --git a/Skills/vphone-guest-control/references/machines.md b/Skills/vphone-guest-control/references/machines.md
index cfb1f41a..33b70099 100644
--- a/Skills/vphone-guest-control/references/machines.md
+++ b/Skills/vphone-guest-control/references/machines.md
@@ -48,12 +48,12 @@ vphone-launchpad-cli vm create myphone [--bundle <version>] \
- **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
+ `Documents/en/firmware/compatibility.md`. Local paths are read in place; URLs are
cached in `~/.vphone/ipsws/`.
- **`--device`** makes an iPad guest: `iPad16,1`, `iPad15,7`, `iPad15,3`,
`iPad15,5`, `iPad16,3`, `iPad16,5`, `iPad17,1` or `iPad17,3`. Without sources
it takes that iPad's newest catalog pairing; with an iPad IPSW that covers
- two sizes it picks the size. See `Documents/Guides/ipados.md`.
+ two sizes it picks the size. See `Documents/en/firmware/ipados.md`.
`AppleTV5,3` makes an Apple TV HD guest on tvOS 26.6: always without a
template or slimming, with the `tvos` preset unless `--preset` names
another. `AppleTV14,1` makes an Apple TV 4K guest the same way, with the
diff --git a/Skills/vphone-guest-control/references/troubleshooting.md b/Skills/vphone-guest-control/references/troubleshooting.md
index 4592be31..68a05626 100644
--- a/Skills/vphone-guest-control/references/troubleshooting.md
+++ b/Skills/vphone-guest-control/references/troubleshooting.md
@@ -80,7 +80,7 @@ migration is hung, not that the display is broken.
`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
+ `Documents/en/help/troubleshooting.md`, then report. Do not recreate the
machine to test a theory.
## Apps and the bootstrap
@@ -88,7 +88,7 @@ migration is hung, not that the display is broken.
- **"Press home to continue" lock screen:** `guest unlock <name>`, or
`{"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`.
+ scope limit on 26.x bases; see `Documents/en/help/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
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/CustomFirmware/ExecutablePatches/ParavirtGPU/CustomFirmwareParavirtGPUIndexOffset.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/CustomFirmware/ExecutablePatches/ParavirtGPU/CustomFirmwareParavirtGPUIndexOffset.swift
index 7d46779a..d8ba6c68 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/CustomFirmware/ExecutablePatches/ParavirtGPU/CustomFirmwareParavirtGPUIndexOffset.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/CustomFirmware/ExecutablePatches/ParavirtGPU/CustomFirmwareParavirtGPUIndexOffset.swift
@@ -47,7 +47,7 @@
//
// The command numbers come from the cloudOS 26.4 (23E5207q) driver, the only
// cloudOS release that carries the `vphone600ap` identity a guest boots from
-// (`Documents/Guides/compatibility.md`). A driver laid out differently fails to
+// (`Documents/en/firmware/compatibility.md`). A driver laid out differently fails to
// resolve and is refused unchanged.
import Foundation
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareSourceSelection.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareSourceSelection.swift
index 926a42e0..1beed0da 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareSourceSelection.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareSourceSelection.swift
@@ -30,7 +30,7 @@ enum VPhoneFirmwareSourceSelection {
/// The compatibility guide whose Tested Environments table rates each build.
static func compatibilityGuide(_ resources: VPhoneResources) -> String {
- let source = resources.base.appendingPathComponent("Documents/Guides/compatibility.md")
+ let source = resources.base.appendingPathComponent("Documents/en/firmware/compatibility.md")
let bundle = resources.base.appendingPathComponent("docs/guides/compatibility.md")
return FileManager.default.fileExists(atPath: source.path) ? source.path : bundle.path
}
diff --git a/VPhoneExecutable/VPhoneVirtualization/Resources/kernelcache_recipes/README.md b/VPhoneExecutable/VPhoneVirtualization/Resources/kernelcache_recipes/README.md
index c7570f91..5ebfe43a 100644
--- a/VPhoneExecutable/VPhoneVirtualization/Resources/kernelcache_recipes/README.md
+++ b/VPhoneExecutable/VPhoneVirtualization/Resources/kernelcache_recipes/README.md
@@ -55,7 +55,7 @@ kexts whose imports have no counterpart there (15 donor kexts instead of 18).
- A kmutil of the base's `builderLayout`: macOS 26.4 or later for the iOS 26 bases,
macOS 15 or 26.0 to 26.3 for the iOS 18 ones. A Mac with the other layout
links over ssh on one that has it (`VPHONE_KMUTIL_SSH`, see
- `Documents/Guides/firmware-preparation.md`).
+ `Documents/en/firmware/firmware-preparation.md`).
- The kmutil of macOS 27 links `kernel-last` too, but keeps every kext's
`__auth_stubs`. After the link, `KernelCollectionStubCalls` makes the calls
through them direct again and seals corecrypto's FIPS HMAC again, so the
diff --git a/VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneGuestLauncher.swift b/VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneGuestLauncher.swift
index 0210a2fa..cfdf3c49 100644
--- a/VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneGuestLauncher.swift
+++ b/VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneGuestLauncher.swift
@@ -31,7 +31,7 @@ public enum VPhoneGuestLaunchError: Error, CustomStringConvertible {
sudo '\(helper.path)' allow '\(guest.path)'
The allowlist is specific to this signature, so repeat after a
- rebuild. See https://github.com/Lakr233/vphone-cli/blob/main/Documents/Guides/host-setup.md
+ rebuild. See https://github.com/Lakr233/vphone-cli/blob/main/Documents/en/get-started/host-setup.md
for host settings.
"""
diff --git a/VPhoneKit/VPhoneCoreKitTests/Firmware/FirmwareMatrixTests.swift b/VPhoneKit/VPhoneCoreKitTests/Firmware/FirmwareMatrixTests.swift
index 2e35e512..65a3ff8c 100644
--- a/VPhoneKit/VPhoneCoreKitTests/Firmware/FirmwareMatrixTests.swift
+++ b/VPhoneKit/VPhoneCoreKitTests/Firmware/FirmwareMatrixTests.swift
@@ -324,7 +324,7 @@ private enum RealData {
.deletingLastPathComponent()
.deletingLastPathComponent()
.deletingLastPathComponent()
- .appendingPathComponent("Documents/Guides/compatibility.md")
+ .appendingPathComponent("Documents/en/firmware/compatibility.md")
return try String(contentsOf: url, encoding: .utf8)
}
diff --git a/VPhoneWebsite/.gitignore b/VPhoneWebsite/.gitignore
index 4097b42e..41c0d50f 100644
--- a/VPhoneWebsite/.gitignore
+++ b/VPhoneWebsite/.gitignore
@@ -1,4 +1,4 @@
-# Generated by scripts/sync-docs.mjs from ../Documents and ../README.md
+# Generated by scripts/sync-docs.mjs from ../Documents and ../Research
/docs/
/doc_build/
/node_modules/
diff --git a/VPhoneWebsite/rspress.config.ts b/VPhoneWebsite/rspress.config.ts
index a7013826..6f80bcbc 100644
--- a/VPhoneWebsite/rspress.config.ts
+++ b/VPhoneWebsite/rspress.config.ts
@@ -4,18 +4,30 @@ import { defineConfig } from '@rspress/core';
// docs/ is generated by `npm run sync` (scripts/sync-docs.mjs).
const docs = path.join(__dirname, 'docs');
-const sidebar = JSON.parse(fs.readFileSync(path.join(docs, 'sidebar.json'), 'utf8'));
+const sidebars = JSON.parse(fs.readFileSync(path.join(docs, 'sidebars.json'), 'utf8'));
+
+// Site chrome per language. The manual is translated; the research notes are English only.
+const languages = [
+ { lang: 'en', label: 'English', prefix: '', manual: 'Manual', research: 'Research', downloads: 'Downloads', tagline: 'Run a virtual iPhone on an Apple Silicon Mac.' },
+ { lang: 'zh', label: '简体中文', prefix: '/zh', manual: '手册', research: '研究笔记', downloads: '下载', tagline: '在 Apple Silicon Mac 上运行虚拟 iPhone。' },
+ { lang: 'ja', label: '日本語', prefix: '/ja', manual: 'マニュアル', research: '研究ノート', downloads: 'ダウンロード', tagline: 'Apple Silicon Mac で仮想 iPhone を動かします。' },
+ { lang: 'ko', label: '한국어', prefix: '/ko', manual: '매뉴얼', research: '연구 노트', downloads: '다운로드', tagline: 'Apple Silicon Mac에서 가상 iPhone을 실행합니다.' },
+];
+
+const manualSections = '^/(?:zh/|ja/|ko/)?(?:get-started|machines|firmware|storage|networking|launchpad|help)/';
export default defineConfig({
root: docs,
// GitHub Pages serves the project site under /vphone-cli/; previews use the same path.
base: '/vphone-cli/',
title: 'vphone',
- description: 'Run a virtual iPhone on an Apple Silicon Mac.',
+ description: languages[0].tagline,
lang: 'en',
+ locales: languages.map(({ lang, label, tagline }) => ({ lang, label, title: 'vphone', description: tagline })),
globalStyles: path.join(__dirname, 'theme/index.css'),
+ globalUIComponents: [path.join(__dirname, 'theme/ResearchLanguageLinks.tsx')],
route: {
- exclude: ['sidebar.json'],
+ exclude: ['sidebars.json'],
},
markdown: {
link: { checkDeadLinks: true },
@@ -23,21 +35,20 @@ export default defineConfig({
themeConfig: {
darkMode: true,
enableContentAnimation: false,
- nav: [
- { text: 'Guide', link: '/guide/introduction', activeMatch: '^/guide/' },
- { text: 'Downloads', link: '/guide/downloads' },
- {
- text: 'Languages',
- items: [
- { text: 'English', link: '/guide/introduction' },
- { text: '中文', link: '/zh/' },
- { text: '日本語', link: '/ja/' },
- { text: '한국어', link: '/ko/' },
- ],
- },
- ],
- sidebar: { '/guide/': sidebar },
socialLinks: [{ icon: 'github', mode: 'link', content: 'https://github.com/Lakr233/vphone-cli' }],
footer: { message: 'vphone-cli · MIT License' },
+ locales: languages.map(({ lang, label, prefix, manual, research, downloads, tagline }) => ({
+ lang,
+ label,
+ title: 'vphone',
+ description: tagline,
+ nav: [
+ { text: manual, link: `${prefix}/get-started/overview`, activeMatch: manualSections },
+ { text: downloads, link: `${prefix}/get-started/downloads` },
+ // Rspress prefixes links in a translated locale; the research notes are English only.
+ { text: research, link: prefix ? 'https://lakr233.github.io/vphone-cli/research/' : '/research/', activeMatch: '^/research/' },
+ ],
+ sidebar: prefix ? { [`${prefix}/`]: sidebars[lang] } : { '/': sidebars.en, '/research/': sidebars.research },
+ })),
},
});
diff --git a/VPhoneWebsite/scripts/sync-docs.mjs b/VPhoneWebsite/scripts/sync-docs.mjs
index dcec6b10..fa8c436c 100644
--- a/VPhoneWebsite/scripts/sync-docs.mjs
+++ b/VPhoneWebsite/scripts/sync-docs.mjs
@@ -1,42 +1,74 @@
// Builds the site's docs/ folder from the repository's own Markdown.
//
-// Documents/ stays the only source: GitHub renders it as is, and this script
-// copies it into the layout Rspress expects. It maps every page to a route,
-// rewrites links between pages to those routes and links to anything else in
-// the repository to GitHub, copies the images pages use, and turns the
-// sections of Documents/README.md into the sidebar.
+// The repository stays the only source: GitHub renders it as is, and this
+// script copies it into the layout Rspress expects.
+//
+// - Documents/<lang>/ is the user manual, one identical tree per language.
+// English pages are served without a prefix, the others under /<lang>/.
+// The `## Section` tables of each Documents/<lang>/README.md are the sidebar.
+// - Research/ is served untranslated under /research/; its sidebar follows
+// the folders.
+// - theme/home/<lang>.md are the home pages.
+//
+// Links between pages become site routes, images are copied, and links to
+// anything else in the repository point to GitHub.
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
+import { bundledLanguages, bundledLanguagesAlias } from 'shiki';
const siteRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const repoRoot = path.resolve(siteRoot, '..');
const outRoot = path.join(siteRoot, 'docs');
const githubBlob = 'https://github.com/Lakr233/vphone-cli/blob/main/';
const githubTree = 'https://github.com/Lakr233/vphone-cli/tree/main/';
-const documentsIndex = 'Documents/README.md';
+const siteURL = 'https://lakr233.github.io/vphone-cli/';
+
+export const languages = ['en', 'zh', 'ja', 'ko'];
+const defaultLanguage = 'en';
// MARK: - Pages
-/** Repository-relative Markdown path -> site route (without extension). */
-const pages = new Map([
- ['README.md', '/guide/introduction'],
- ['Documents/Downloads/README.md', '/guide/downloads'],
- ['Documents/README_zh.md', '/zh/'],
- ['Documents/README_ja.md', '/ja/'],
- ['Documents/README_ko.md', '/ko/'],
-]);
-for (const name of fs.readdirSync(path.join(repoRoot, 'Documents/Guides')).sort()) {
- if (name.endsWith('.md')) {
- pages.set(`Documents/Guides/${name}`, `/guide/${name.replace(/\.md$/, '')}`);
+function walk(directory) {
+ const absolute = path.join(repoRoot, directory);
+ return fs
+ .readdirSync(absolute, { withFileTypes: true })
+ .sort((a, b) => a.name.localeCompare(b.name))
+ .flatMap((entry) => {
+ const child = `${directory}/${entry.name}`;
+ if (entry.isDirectory()) {
+ return walk(child);
+ }
+ return entry.name.endsWith('.md') ? [child] : [];
+ });
+}
+
+function prefix(language) {
+ return language === defaultLanguage ? '' : `/${language}`;
+}
+
+/** Repository-relative Markdown path -> { route, language }. */
+const pages = new Map();
+
+for (const language of languages) {
+ for (const source of walk(`Documents/${language}`)) {
+ const relative = source.slice(`Documents/${language}/`.length).replace(/\.md$/, '');
+ const route = relative === 'README' ? `${prefix(language)}/` : `${prefix(language)}/${relative}`;
+ pages.set(source, { route, language });
}
}
-// The contributors section of the documents index becomes a page of its own.
-const contributingRoute = '/guide/contributing';
+for (const source of walk('Research')) {
+ const relative = source.slice('Research/'.length).replace(/\.md$/, '');
+ const route = relative === 'README' ? '/research/' : `/research/${relative.replace(/(^|\/)README$/, '$1')}`;
+ pages.set(source, { route, language: defaultLanguage });
+}
-function routeFile(route) {
- return path.join(outRoot, route.endsWith('/') ? `${route}index.md` : `${route}.md`);
+/** The output file of a route; the default language lives in docs/en/. */
+function routeFile(route, language) {
+ const local = language === defaultLanguage ? route : route.slice(language.length + 1);
+ const relative = local.endsWith('/') ? `${local}index.md` : `${local}.md`;
+ return path.join(outRoot, language, relative);
}
// MARK: - Links
@@ -57,43 +89,112 @@ function rewriteTarget(fromFile, target) {
}
const { repoPath, anchor } = resolveTarget(fromFile, target);
const suffix = anchor ? `#${anchor}` : '';
- if (repoPath === documentsIndex) {
- return anchor === 'for-contributors' ? contributingRoute : '/guide/introduction#documentation';
- }
if (pages.has(repoPath)) {
- return pages.get(repoPath) + suffix;
+ const page = pages.get(repoPath);
+ // Rspress resolves links on a translated page inside that language, and the
+ // research notes exist only in English, so those links leave the locale.
+ const fromLanguage = pages.get(fromFile)?.language ?? defaultLanguage;
+ if (page.language !== fromLanguage) {
+ return siteURL + page.route.slice(1) + suffix;
+ }
+ return page.route + suffix;
}
- if (/\.(png|jpe?g|gif|svg|webp)$/i.test(repoPath)) {
+ if (/\.(png|jpe?g|gif|svg|webp)$/i.test(repoPath) && fs.existsSync(path.join(repoRoot, repoPath))) {
images.add(repoPath);
return `/images/${repoPath}`;
}
const absolute = path.join(repoRoot, repoPath);
const isDirectory = fs.existsSync(absolute) && fs.statSync(absolute).isDirectory();
- return (isDirectory ? githubTree : githubBlob) + repoPath + suffix;
+ return encodeURI((isDirectory ? githubTree : githubBlob) + repoPath) + suffix;
}
-/** Rewrites Markdown and HTML link targets outside fenced code. */
+/** Rewrites Markdown and HTML link targets outside code. */
function rewriteLinks(fromFile, text) {
- let inFence = false;
- return text
- .split('\n')
- .map((line) => {
- if (/^\s*```/.test(line)) {
- inFence = !inFence;
- return line;
+ return mapOutsideCode(text, (prose) =>
+ prose
+ .replace(/(\]\()(<[^>]+>|[^)\s]+)((?:\s+"[^"]*")?\))/g, (_, open, target, close) => {
+ const bare = target.replace(/^<|>$/g, '');
+ return open + rewriteTarget(fromFile, bare) + close;
+ })
+ .replace(/^(\[[^\]]+\]:\s*)(\S+)/gm, (_, open, target) => open + rewriteTarget(fromFile, target))
+ .replace(/((?:href|src)=")([^"]+)(")/g, (_, open, target, close) => open + rewriteTarget(fromFile, target) + close),
+ );
+}
+
+/**
+ * Applies `transform` to the text outside fenced code blocks and inline code
+ * spans. Inline spans may wrap onto the next line, so the text between fences
+ * is handled a paragraph at a time.
+ */
+function mapOutsideCode(text, transform) {
+ const output = [];
+ let prose = [];
+ let fence = null;
+ const flush = () => {
+ if (prose.length > 0) {
+ output.push(...prose.join('\n').split(/(\n[ \t]*\n)/).map((chunk) => mapProse(chunk, transform)).join('').split('\n'));
+ prose = [];
+ }
+ };
+ for (const line of text.split('\n')) {
+ const marker = /^\s*(`{3,}|~{3,})/.exec(line);
+ if (fence || marker) {
+ flush();
+ if (marker && !fence) {
+ fence = marker[1];
+ } else if (marker && marker[1][0] === fence[0] && marker[1].length >= fence.length) {
+ fence = null;
}
- if (inFence) {
- return line;
+ output.push(line);
+ } else {
+ prose.push(line);
+ }
+ }
+ flush();
+ return output.join('\n');
+}
+
+/** Splits one paragraph on inline code spans (a run of backticks closed by an equal run). */
+function mapProse(paragraph, transform) {
+ let result = '';
+ let plain = '';
+ let index = 0;
+ while (index < paragraph.length) {
+ const run = /^`+/.exec(paragraph.slice(index));
+ if (run) {
+ const closing = new RegExp(`(?<!\`)${run[0]}(?!\`)`, 'g');
+ closing.lastIndex = index + run[0].length;
+ const close = closing.exec(paragraph);
+ if (close) {
+ result += transform(plain) + paragraph.slice(index, close.index + run[0].length);
+ plain = '';
+ index = close.index + run[0].length;
+ continue;
}
- return line
- .replace(/(\]\()([^)\s]+)(\))/g, (_, open, target, close) => open + rewriteTarget(fromFile, target) + close)
- .replace(/((?:href|src)=")([^"]+)(")/g, (_, open, target, close) => open + rewriteTarget(fromFile, target) + close);
- })
- .join('\n');
+ plain += run[0];
+ index += run[0].length;
+ continue;
+ }
+ plain += paragraph[index];
+ index += 1;
+ }
+ return result + transform(plain);
}
// MARK: - Page bodies
+/** Code fences in a language Shiki does not know fail the build; they become plain text. */
+const fenceAliases = { plist: 'xml', entitlements: 'xml', zsh: 'sh', asm: 'asm', objc: 'objective-c' };
+
+function normalizeFences(text) {
+ return text.replace(/^(\s*(?:`{3,}|~{3,}))([^\s`{]+)(.*)$/gm, (line, fence, language, rest) => {
+ const lower = language.toLowerCase();
+ const mapped = fenceAliases[lower] ?? lower;
+ const known = mapped in bundledLanguages || mapped in bundledLanguagesAlias;
+ return `${fence}${known ? mapped : 'text'}${rest}`;
+ });
+}
+
/** GitHub alerts (`> [!WARNING]`) become Rspress containers. */
function convertAlerts(text) {
return text.replace(/^> \[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]\n((?:>.*\n?)*)/gm, (_, kind, body) => {
@@ -107,23 +208,43 @@ function convertAlerts(text) {
function dropRepositoryChrome(text) {
return text
.replace(/^<div align="right">.*<\/div>\n+/m, '')
- .replace(/^\[Documentation\]\([^)]*\)( · .*)?\n+/m, '');
+ .replace(/^\[[^\]]+\]\([^)]*\)( · \[[^\]]+\]\([^)]*\))*\n+(?=#|\S)/, '');
}
-function writePage(route, body) {
- const file = routeFile(route);
+/**
+ * Research notes are plain Markdown written for GitHub. Rspress compiles
+ * pages as MDX, so characters MDX treats as syntax are escaped outside code:
+ * braces, `<` that does not open a known HTML tag, and HTML comments.
+ */
+const htmlTags = new Set([
+ 'a', 'b', 'br', 'code', 'details', 'div', 'em', 'i', 'img', 'kbd', 'li', 'ol', 'p', 'pre', 'span',
+ 'strong', 'sub', 'summary', 'sup', 'table', 'tbody', 'td', 'th', 'thead', 'tr', 'u', 'ul',
+]);
+
+function escapeForMdx(text) {
+ return mapOutsideCode(text.replace(/<!--[\s\S]*?-->/g, ''), (part) =>
+ part
+ .replace(/<((?:https?|mailto):[^>\s]+)>/g, '[$1]($1)')
+ .replace(/[{}]/g, (brace) => `\\${brace}`)
+ .replace(/<(\/?)([^>\s/]*)/g, (match, slash, name) => (htmlTags.has(name.toLowerCase()) ? match : `&lt;${slash}${name}`))
+ .replace(/<(img|br)\b([^>]*?)\s*\/?>/gi, '<$1$2 />'),
+ );
+}
+
+function writeFile(file, body) {
fs.mkdirSync(path.dirname(file), { recursive: true });
fs.writeFileSync(file, body);
}
-// MARK: - Sidebar
-
function titleOf(text) {
- return /^# (.+)$/m.exec(text)?.[1].trim();
+ return /^# (.+)$/m.exec(text)?.[1].trim().replace(/`/g, '');
}
-/** The `## Section` tables of Documents/README.md, as Rspress sidebar groups. */
-function sidebarFromIndex(indexText) {
+// MARK: - Sidebars
+
+/** The `## Section` tables of a manual index, as Rspress sidebar groups. */
+function manualSidebar(indexSource) {
+ const indexText = fs.readFileSync(path.join(repoRoot, indexSource), 'utf8');
const groups = [];
let current;
for (const line of indexText.split('\n')) {
@@ -135,33 +256,60 @@ function sidebarFromIndex(indexText) {
}
const row = /^\| \[([^\]]+)\]\(([^)]+)\) \|/.exec(line);
if (current && row) {
- const { repoPath } = resolveTarget(documentsIndex, row[2]);
- if (pages.has(repoPath)) {
- current.items.push({ text: row[1], link: pages.get(repoPath) });
+ const { repoPath } = resolveTarget(indexSource, row[2]);
+ if (!pages.has(repoPath)) {
+ throw new Error(`${indexSource} links to ${row[2]}, which is not a manual page`);
}
+ current.items.push({ text: row[1], link: pages.get(repoPath).route });
}
}
return groups.filter((group) => group.items.length > 0);
}
+/** Research folders, as collapsed sidebar groups titled by their notes' headings. */
+function researchSidebar(titles) {
+ const groups = new Map();
+ for (const [source, { route }] of pages) {
+ if (!source.startsWith('Research/') || source === 'Research/README.md') {
+ continue;
+ }
+ const parts = source.slice('Research/'.length).split('/');
+ const group = parts.length > 1 ? parts.slice(0, -1).join(' / ') : 'General';
+ if (!groups.has(group)) {
+ groups.set(group, []);
+ }
+ groups.get(group).push({ text: titles.get(source) ?? parts.at(-1), link: route });
+ }
+ const ordered = [...groups].sort(([a], [b]) => (a === 'General' ? -1 : b === 'General' ? 1 : a.localeCompare(b)));
+ return [
+ { text: 'Research', items: [{ text: 'Index', link: '/research/' }] },
+ ...ordered.map(([text, items]) => ({ text, collapsible: true, collapsed: true, items })),
+ ];
+}
+
// MARK: - Run
fs.rmSync(outRoot, { recursive: true, force: true });
-fs.mkdirSync(outRoot, { recursive: true });
-for (const [source, route] of pages) {
- const text = fs.readFileSync(path.join(repoRoot, source), 'utf8');
- // The translated overviews are single pages outside the English sidebar.
- const frontmatter = route.startsWith('/guide/') ? '' : '---\nsidebar: false\n---\n\n';
- writePage(route, frontmatter + rewriteLinks(source, convertAlerts(dropRepositoryChrome(text))));
+const titles = new Map();
+for (const [source, { route, language }] of pages) {
+ const raw = fs.readFileSync(path.join(repoRoot, source), 'utf8');
+ titles.set(source, titleOf(raw));
+ let body = rewriteLinks(source, convertAlerts(dropRepositoryChrome(normalizeFences(raw))));
+ if (source.startsWith('Research/')) {
+ body = escapeForMdx(body);
+ }
+ // A manual index is the sidebar on the site, not a page of its own.
+ const isManualIndex = source.startsWith('Documents/') && source.endsWith('/README.md');
+ if (!isManualIndex) {
+ writeFile(routeFile(route, language), body);
+ }
}
-const indexText = fs.readFileSync(path.join(repoRoot, documentsIndex), 'utf8');
-const contributors = /^## For Contributors\n([\s\S]*?)(?=^## |(?![\s\S]))/m.exec(indexText);
-if (!contributors) {
- throw new Error(`${documentsIndex} has no "## For Contributors" section`);
+for (const language of languages) {
+ const home = path.join(siteRoot, 'theme/home', `${language}.md`);
+ fs.copyFileSync(home, routeFile(`${prefix(language)}/`, language));
}
-writePage(contributingRoute, rewriteLinks(documentsIndex, `# Contributing\n\n${contributors[1].trim()}\n`));
for (const image of images) {
const destination = path.join(outRoot, 'public/images', image);
@@ -169,17 +317,19 @@ for (const image of images) {
fs.copyFileSync(path.join(repoRoot, image), destination);
}
-const sidebar = [
- { text: 'Overview', items: [{ text: 'Introduction', link: '/guide/introduction' }] },
- ...sidebarFromIndex(indexText),
- { text: 'Project', items: [{ text: 'Contributing', link: contributingRoute }] },
-];
-const listed = new Set(sidebar.flatMap((group) => group.items.map((item) => item.link)));
-const unlisted = [...pages].filter(([source, route]) => route.startsWith('/guide/') && !listed.has(route));
-if (unlisted.length > 0) {
- throw new Error(`Pages missing from ${documentsIndex}: ${unlisted.map(([source]) => source).join(', ')}`);
+const sidebars = { research: researchSidebar(titles) };
+for (const language of languages) {
+ const index = `Documents/${language}/README.md`;
+ const sidebar = manualSidebar(index);
+ const listed = new Set(sidebar.flatMap((group) => group.items.map((item) => item.link)));
+ const unlisted = [...pages]
+ .filter(([source, page]) => page.language === language && source.startsWith(`Documents/${language}/`))
+ .filter(([source, page]) => source !== index && !listed.has(page.route));
+ if (unlisted.length > 0) {
+ throw new Error(`Pages missing from ${index}: ${unlisted.map(([source]) => source).join(', ')}`);
+ }
+ sidebars[language] = sidebar;
}
-fs.writeFileSync(path.join(outRoot, 'sidebar.json'), `${JSON.stringify(sidebar, null, 2)}\n`);
-fs.copyFileSync(path.join(siteRoot, 'theme/home.md'), path.join(outRoot, 'index.md'));
+writeFile(path.join(outRoot, 'sidebars.json'), `${JSON.stringify(sidebars, null, 2)}\n`);
-console.log(`synced ${pages.size + 1} pages, ${images.size} images, ${sidebar.length} sidebar groups`);
+console.log(`synced ${pages.size} pages, ${images.size} images`);
diff --git a/VPhoneWebsite/theme/ResearchLanguageLinks.tsx b/VPhoneWebsite/theme/ResearchLanguageLinks.tsx
new file mode 100644
index 00000000..78c53c2c
--- /dev/null
+++ b/VPhoneWebsite/theme/ResearchLanguageLinks.tsx
@@ -0,0 +1,25 @@
+import { useEffect } from 'react';
+
+// The research notes are English only, so on a research page the language
+// switcher's links (/zh/research/...) lead nowhere. Send them to that
+// language's home instead.
+const translated = /^(\/vphone-cli)?\/(zh|ja|ko)\/research(\/|\.html|$)/;
+
+export default function ResearchLanguageLinks() {
+ useEffect(() => {
+ const onClick = (event: MouseEvent) => {
+ const anchor = (event.target as Element | null)?.closest?.('a');
+ const href = anchor?.getAttribute('href');
+ const match = href ? translated.exec(href) : null;
+ if (!match) {
+ return;
+ }
+ event.preventDefault();
+ event.stopPropagation();
+ window.location.assign(`${match[1] ?? ''}/${match[2]}/`);
+ };
+ document.addEventListener('click', onClick, true);
+ return () => document.removeEventListener('click', onClick, true);
+ }, []);
+ return null;
+}
diff --git a/VPhoneWebsite/theme/home.md b/VPhoneWebsite/theme/home.md
deleted file mode 100644
index 7fe7684d..00000000
--- a/VPhoneWebsite/theme/home.md
+++ /dev/null
@@ -1,18 +0,0 @@
----
-pageType: home
-
-hero:
- name: vphone
- text: A virtual iPhone on your Mac
- tagline: iOS on Apple's Virtualization.framework and PCC research VMs, for security research, reverse engineering and debugging.
- actions:
- - theme: brand
- text: Get Started
- link: /guide/introduction
- - theme: alt
- text: Download
- link: /guide/downloads
- - theme: alt
- text: GitHub
- link: https://github.com/Lakr233/vphone-cli
----
diff --git a/VPhoneWebsite/theme/home/en.md b/VPhoneWebsite/theme/home/en.md
new file mode 100644
index 00000000..c435d064
--- /dev/null
+++ b/VPhoneWebsite/theme/home/en.md
@@ -0,0 +1,29 @@
+---
+pageType: home
+
+hero:
+ name: vphone
+ text: A virtual iPhone on your Mac
+ tagline: iOS on Apple's Virtualization.framework and PCC research VMs, for security research, reverse engineering and debugging.
+ actions:
+ - theme: brand
+ text: Quick Start
+ link: /get-started/quick-start
+ - theme: alt
+ text: Manual
+ link: /get-started/overview
+ - theme: alt
+ text: Research Notes
+ link: /research/
+
+features:
+ - title: Set up
+ details: Requirements, host security settings and the four steps in Launchpad.
+ link: /get-started/quick-start
+ - title: Daily use
+ details: Create, start and back up VMs, pick firmware, configure the network.
+ link: /machines/create-and-run
+ - title: Troubleshooting
+ details: Launch refusals, restore failures and guest problems, by symptom.
+ link: /help/troubleshooting
+---
diff --git a/VPhoneWebsite/theme/home/ja.md b/VPhoneWebsite/theme/home/ja.md
new file mode 100644
index 00000000..954f4647
--- /dev/null
+++ b/VPhoneWebsite/theme/home/ja.md
@@ -0,0 +1,29 @@
+---
+pageType: home
+
+hero:
+ name: vphone
+ text: Mac で仮想 iPhone を動かす
+ tagline: Apple の Virtualization.framework と PCC リサーチ VM で iOS を実行します。セキュリティ研究、リバースエンジニアリング、デバッグ向けです。
+ actions:
+ - theme: brand
+ text: クイックスタート
+ link: /ja/get-started/quick-start
+ - theme: alt
+ text: マニュアル
+ link: /ja/get-started/overview
+ - theme: alt
+ text: 研究ノート(英語)
+ link: /research/
+
+features:
+ - title: セットアップ
+ details: 動作要件、ホストのセキュリティ設定、Launchpad での 4 つの手順。
+ link: /ja/get-started/quick-start
+ - title: 基本的な使い方
+ details: VM の作成、起動、バックアップ、ファームウェアの選択、ネットワークの設定。
+ link: /ja/machines/create-and-run
+ - title: トラブルシューティング
+ details: 起動拒否、復元失敗、ゲスト内の問題を症状別に探せます。
+ link: /ja/help/troubleshooting
+---
diff --git a/VPhoneWebsite/theme/home/ko.md b/VPhoneWebsite/theme/home/ko.md
new file mode 100644
index 00000000..e06fa37d
--- /dev/null
+++ b/VPhoneWebsite/theme/home/ko.md
@@ -0,0 +1,29 @@
+---
+pageType: home
+
+hero:
+ name: vphone
+ text: Mac에서 가상 iPhone 실행하기
+ tagline: Apple의 Virtualization.framework와 PCC 연구용 VM으로 iOS를 실행합니다. 보안 연구, 리버스 엔지니어링, 디버깅에 사용합니다.
+ actions:
+ - theme: brand
+ text: 빠른 시작
+ link: /ko/get-started/quick-start
+ - theme: alt
+ text: 매뉴얼
+ link: /ko/get-started/overview
+ - theme: alt
+ text: 연구 노트(영어)
+ link: /research/
+
+features:
+ - title: 설정
+ details: 요구 사항, 호스트 보안 설정, Launchpad에서 진행하는 네 단계.
+ link: /ko/get-started/quick-start
+ - title: 기본 사용법
+ details: VM 생성, 시작, 백업, 펌웨어 선택, 네트워크 설정.
+ link: /ko/machines/create-and-run
+ - title: 문제 해결
+ details: 실행 거부, 복원 실패, 게스트 문제를 증상별로 찾습니다.
+ link: /ko/help/troubleshooting
+---
diff --git a/VPhoneWebsite/theme/home/zh.md b/VPhoneWebsite/theme/home/zh.md
new file mode 100644
index 00000000..e5935f30
--- /dev/null
+++ b/VPhoneWebsite/theme/home/zh.md
@@ -0,0 +1,29 @@
+---
+pageType: home
+
+hero:
+ name: vphone
+ text: 在 Mac 上运行虚拟 iPhone
+ tagline: 基于 Apple Virtualization.framework 和 PCC 研究虚拟机运行 iOS,用于安全研究、逆向工程和调试。
+ actions:
+ - theme: brand
+ text: 快速开始
+ link: /zh/get-started/quick-start
+ - theme: alt
+ text: 使用手册
+ link: /zh/get-started/overview
+ - theme: alt
+ text: 研究笔记(英文)
+ link: /research/
+
+features:
+ - title: 安装与设置
+ details: 系统要求、宿主机安全设置,以及在 Launchpad 中完成的四个步骤。
+ link: /zh/get-started/quick-start
+ - title: 日常使用
+ details: 创建、启动和备份虚拟机,选择固件,配置网络。
+ link: /zh/machines/create-and-run
+ - title: 故障排除
+ details: 按症状排查启动被拒、恢复失败及客户机问题。
+ link: /zh/help/troubleshooting
+---