Run a virtual iPhone on an Apple Silicon Mac.
Swift
refactor: use PascalCase document folders
Lakre5c51bd5784e
diff --git a/.gitignore b/.gitignoreindex de2ccf33..c7f0737c 100644--- a/.gitignore+++ b/.gitignore@@ -165,7 +165,7 @@ instance/.scrapy# Sphinx documentation-docs/_build/+Documents/_build/# PyBuilder.pybuilder/@@ -331,7 +331,7 @@ __marimo__//.swiftpm*.ipsw/updates-cdn-/research/jb_asm_refs+/Research/jb_asm_refs/references/Scripts/VPhoned/vphoned/cfw_input/@@ -345,9 +345,9 @@ tar.????????setup_logs//testing_results/.ida-mcp-/research/reference/xnu-/research/artifacts-/research/xnu+/Research/Reference/xnu+/Research/artifacts+/Research/xnu/vm/vm.backups/vm-*/diff --git a/AGENTS.md b/AGENTS.mdindex 051a8f5a..f9de2ee6 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -8,9 +8,9 @@ Virtual iPhone boot tool using Apple's Virtualization.framework with PCC researc- **Test:** `swift test`; then `zsh Scripts/check_aux.sh` for bundle admission gates- **Boot (GUI):** `vphone-cli vm launch <name>`- **Boot (DFU):** `vphone-cli vm launch <name> --dfu`-- **AMFI refuses `vphone-vm`?** Use the bundled `vphone-amfi-allow` helper as shown in `docs/guides/host-setup.md`. Repeat after every build because it allowlists cdhashes. See Key Patterns.-- **Restore:** `vphone-cli restore`, in process. Vendored libirecovery + idevicerestore (`Sources/MobileRecoveryCore`, `Sources/MobileRestoreCore`) over the `AppleMobileDeviceLibrary` xcframeworks. No interpreter, no environment to provision, no setup step. See `research/restore/p2_restore_off_python.md`.-- **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 the user runs. Both are in `docs/guides/host-setup.md`; neither is installed by this project.+- **AMFI refuses `vphone-vm`?** Use the bundled `vphone-amfi-allow` helper as shown in `Documents/Guides/host-setup.md`. Repeat after every build because it allowlists cdhashes. See Key Patterns.+- **Restore:** `vphone-cli restore`, in process. Vendored libirecovery + idevicerestore (`Sources/MobileRecoveryCore`, `Sources/MobileRestoreCore`) over the `AppleMobileDeviceLibrary` xcframeworks. No interpreter, no environment to provision, no setup step. See `Research/Restore/p2_restore_off_python.md`.+- **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 the user runs. Both are in `Documents/Guides/host-setup.md`; neither is installed by this project.- **Language:** Swift 6.0 (SwiftPM), private APIs via [Dynamic](https://github.com/mhdhejazi/Dynamic). This package's own manifest is `swift-tools-version:6.0`, but the **toolchain floor is Swift 6.2**: `libcapstone-spm` declares 6.2 so that it can reach `CSetting.disableWarning` instead of `.unsafeFlags`, which is what lets it be depended on by version at all.- **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.- **Tiers.** Three environments run code here and the rules differ. **build** (the machine that builds the `.app`) may use Xcode, `xcrun`, clang, swift, git and Homebrew. **dist** (the shipped `.app`, on a clean macOS) may use `/usr/lib`, `/System` and the bundle — nothing else, no `PATH` lookup. **guest** (inside the VM) is out of host self-containment scope. Every script declares its tier on **line 2** (`# vphone-tier: dist`); `Scripts/dist_manifest.sh` reads those and is what `Scripts/build.sh` stages from, so a script that declares nothing ships nowhere. `Scripts/check_aux.sh` runs the admission gates. The dist tier's registered-exception list is **empty** and a release requires it to stay that way.@@ -21,11 +21,11 @@ Virtual iPhone boot tool using Apple's Virtualization.framework with PCC researc- Ignore `/TODO.md` if it exists locally; it is intentionally not part of the repo workflow anymore.- Track plan, progress, assumptions, blockers, and next actions in commit history, code comments when warranted, and current research docs instead of a repo TODO file.-For any changes applying new patches, also update research/0_binary_patch_comparison.md. Dont forget this.+For any changes applying new patches, also update Research/0_binary_patch_comparison.md. Dont forget this.## Local Skills-- If working on kernel analysis, symbolication lookups, or kernel patch reasoning, read `skills/kernel-analysis-vphone600/SKILL.md` first.+- If working on kernel analysis, symbolication lookups, or kernel patch reasoning, read `Skills/kernel-analysis-vphone600/SKILL.md` first.- Use this skill as the default procedure for `vphone600` kernel work.## Firmware Mode@@ -35,7 +35,7 @@ The guest contains vphoned and required system patches; package-managerbootstrap and first-boot installation are outside this project. Do not addanother public variant.-See `research/` for detailed firmware pipeline, component origins, patch breakdowns, and boot flow documentation.+See `Research/` for detailed firmware pipeline, component origins, patch breakdowns, and boot flow documentation.## Architecture@@ -189,15 +189,15 @@ Siblings/ # Guest component sources/provenance; separate├── TweakLoader/ VPRegister/ # Loader and iOS 27 app registrar└── gpu/ # PCC firmware provenance; no Apple binary-research/ # Detailed firmware/patch documentation+Research/ # Detailed firmware/patch documentation```### Key Patterns- **Three host binaries, one of them entitled.** `vphone-cli` carries no entitlements, so it launches on any host and is always there to explain what is wrong. `vphone-vm` holds all 7 private keys and is the only thing amfid can refuse. `vphone-archive` does the unpacking. **Do not sign `vphone-cli` with entitlements** — that is how it used to be, and it is why the entry point could not start without a bypass already running.-- **The AMFI bypass is ours, and it writes heap, not code.** `vphone-amfi-allow` (`Sources/VPhoneAMFIAllow/`, this project's copy of [Lakr233/amfi-allow](https://github.com/Lakr233/amfi-allow)) puts the cdhashes of both `vphone-vm` copies into `/Library/Preferences/com.apple.security.coderequirements.plist` — a file AMFI already reads — and flips one byte of `_isRunningInternalBuild` in amfid's `AMFIRequirementsManager` singleton so it consults that file. It is an **allowlist**, scoped to the cdhashes you name; do not describe it as a global switch. The helper's `allow`, `status`, and `off` commands manage it; see `docs/guides/host-setup.md`. It is a **per-build** step, because a cdhash changes with every signature. It must be **arm64e** to match amfid's slice, and `Scripts/build.sh` builds it with clang. The heap write is the load-bearing detail: `vphone-letmein` and LLDB-based tools dirty an executable page, and on a host with `vm.cs_system_enforcement = 1` the kernel kills amfid for that and takes the guest with it.+- **The AMFI bypass is ours, and it writes heap, not code.** `vphone-amfi-allow` (`Sources/VPhoneAMFIAllow/`, this project's copy of [Lakr233/amfi-allow](https://github.com/Lakr233/amfi-allow)) puts the cdhashes of both `vphone-vm` copies into `/Library/Preferences/com.apple.security.coderequirements.plist` — a file AMFI already reads — and flips one byte of `_isRunningInternalBuild` in amfid's `AMFIRequirementsManager` singleton so it consults that file. It is an **allowlist**, scoped to the cdhashes you name; do not describe it as a global switch. The helper's `allow`, `status`, and `off` commands manage it; see `Documents/Guides/host-setup.md`. It is a **per-build** step, because a cdhash changes with every signature. It must be **arm64e** to match amfid's slice, and `Scripts/build.sh` builds it with clang. The heap write is the load-bearing detail: `vphone-letmein` and LLDB-based tools dirty an executable page, and on a host with `vm.cs_system_enforcement = 1` the kernel kills amfid for that and takes the guest with it.- **Guest launches go through `VPhoneGuestLaunchPlanner`** (`VPhoneCore`). It resolves `vphone-vm` as a sibling of the running image — never through `PATH` — checks its two PV=3 entitlements, then probes with `vphone-vm --help` for SIGKILL. A refusal is reported with the exact command the user has to run; the planner never arranges a bypass itself. Never spawn the guest directly.-- **Restore runs in `vphone-cli`'s own process.** `VPhoneRestore` calls `vphone_restore_run()` in `MobileRestoreCore`; there is no subprocess, no bridge script and no environment to resolve first. The three commands the old Python bridge exposed became `restore --get-shsh`, `restore` and `restore --offline`; its fourth, `usbmux-list`, had no call site and was not ported. `research/restore/p2_restore_off_python.md` has the decision and the behaviour table.+- **Restore runs in `vphone-cli`'s own process.** `VPhoneRestore` calls `vphone_restore_run()` in `MobileRestoreCore`; there is no subprocess, no bridge script and no environment to resolve first. The three commands the old Python bridge exposed became `restore --get-shsh`, `restore` and `restore --offline`; its fourth, `usbmux-list`, had no call site and was not ported. `Research/Restore/p2_restore_off_python.md` has the decision and the behaviour table.- **Private API access:** Via [Dynamic](https://github.com/mhdhejazi/Dynamic) library (runtime method dispatch from pure Swift). No ObjC bridge.- **App lifecycle:** `VPhoneVM/main.swift` → `VPhoneGuestApp.run()` → `NSApplication` + `VPhoneVirtualMachineAppDelegate`. Entry points hold no logic.- **Configuration:** `ArgumentParser` → `VPhoneBootCLI` (in `VPhoneCore`, parsed by both binaries) → `VPhoneVirtualMachine.Options` → `VZVirtualMachineConfiguration`.@@ -247,7 +247,7 @@ There is none, and adding any is a regression.returns nothing; that is the standing check.- There is no environment to activate and no dependency list to install. Therestore backend was the last holdout and is now `Sources/VPhoneRestore` over- two vendored C targets — see `research/restore/p2_restore_off_python.md`.+ two vendored C targets — see `Research/Restore/p2_restore_off_python.md`.- A patch, a probe, a format reader or a device protocol belongs in Swift,where it is built, signed, gated by `Scripts/check_aux.sh` and tested witheverything else. Adding an interpreter back brings with it a provisioningdiff --git a/docs/guides/compatibility.md b/Documents/Guides/compatibility.mdsimilarity index 97%rename from docs/guides/compatibility.mdrename to Documents/Guides/compatibility.mdindex e9dc928a..64ff65f2 100644--- a/docs/guides/compatibility.md+++ b/Documents/Guides/compatibility.md@@ -1,6 +1,6 @@# Firmware compatibility-[Documentation](../README.md) · [Create a VM](create-and-run.md) · [Patch inventory](../../research/0_binary_patch_comparison.md)+[Documentation](../README.md) · [Create a VM](create-and-run.md) · [Patch inventory](../../Research/0_binary_patch_comparison.md)## Tested Environmentsdiff --git a/docs/guides/create-and-run.md b/Documents/Guides/create-and-run.mdsimilarity index 100%rename from docs/guides/create-and-run.mdrename to Documents/Guides/create-and-run.mddiff --git a/docs/guides/host-setup.md b/Documents/Guides/host-setup.mdsimilarity index 97%rename from docs/guides/host-setup.mdrename to Documents/Guides/host-setup.mdindex 00830bce..42c2d61c 100644--- a/docs/guides/host-setup.md+++ b/Documents/Guides/host-setup.md@@ -61,4 +61,4 @@ For a distributed app without a source checkout, run `vphone-cli host preflight`## What the build contains-`vphone-cli` orchestrates the work without private entitlements. `vphone-vm` is the signed, entitled GUI/VM process. `vphone-archive` handles archives. The project also bundles 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.+`vphone-cli` orchestrates the work without private entitlements. `vphone-vm` is the signed, entitled GUI/VM process. `vphone-archive` handles archives. The project also bundles 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/docs/guides/troubleshooting.md b/Documents/Guides/troubleshooting.mdsimilarity index 100%rename from docs/guides/troubleshooting.mdrename to Documents/Guides/troubleshooting.mddiff --git a/docs/README.md b/Documents/README.mdsimilarity index 67%rename from docs/README.mdrename to Documents/README.mdindex 0ecb17ad..cb5d55ee 100644--- a/docs/README.md+++ b/Documents/README.md@@ -1,15 +1,15 @@# Documentation-[Project overview](../README.md) · [Research notes](../research/README.md)+[Project overview](../README.md) · [Research notes](../Research/README.md)-Start with the [one-command VM flow](guides/create-and-run.md). The guides below describe the current **JB-only** CLI. Older patch variants and installation experiments remain in research notes as historical context, not supported user workflows.+Start with the [one-command VM flow](Guides/create-and-run.md). The guides below describe the current **JB-only** CLI. Older patch variants and installation experiments remain in research notes as historical context, not supported user workflows.| Guide | Use it for || --- | --- |-| [Host setup](guides/host-setup.md) | Apple Silicon, SIP/AMFI settings, signing and preflight |-| [Create and run a VM](guides/create-and-run.md) | Firmware inputs, full or manual pipeline, vphoned, storage and backups |-| [Compatibility](guides/compatibility.md) | Verified firmware pairs and what the checks actually prove |-| [Troubleshooting](guides/troubleshooting.md) | Launch refusals, restore failures, Home key and app problems |+| [Host setup](Guides/host-setup.md) | Apple Silicon, SIP/AMFI settings, signing and preflight |+| [Create and run a VM](Guides/create-and-run.md) | Firmware inputs, full or manual pipeline, vphoned, storage and backups |+| [Compatibility](Guides/compatibility.md) | Verified firmware pairs and what the checks actually prove |+| [Troubleshooting](Guides/troubleshooting.md) | Launch refusals, restore failures, Home key and app problems |## Translations@@ -19,7 +19,7 @@ These pages give a translated overview and quick start. The English guides above## For contributors-- [Research index](../research/README.md) groups the patch and implementation records by subject.-- [Patch inventory](../research/0_binary_patch_comparison.md) is the canonical per-component comparison.+- [Research index](../Research/README.md) groups the patch and implementation records by subject.+- [Patch inventory](../Research/0_binary_patch_comparison.md) is the canonical per-component comparison.- `zsh Scripts/build.sh` builds and bundles the application; `swift test` and `zsh Scripts/check_aux.sh` run the tests and bundle checks.- `vphone-cli <group> --help` shows the CLI command surface.diff --git a/docs/README_ja.md b/Documents/README_ja.mdsimilarity index 91%rename from docs/README_ja.mdrename to Documents/README_ja.mdindex 75efe667..d0aa77c9 100644--- a/docs/README_ja.md+++ b/Documents/README_ja.md@@ -10,7 +10,7 @@ Apple の Virtualization.framework と PCC 研究用 VM 基盤を使って、仮## クイックスタート-Apple Silicon、macOS 15 以降、および PV=3 研究用 VM と `vphone-vm` の権限を許可する[ホスト設定](guides/host-setup.md)が必要です。+Apple Silicon、macOS 15 以降、および PV=3 研究用 VM と `vphone-vm` の権限を許可する[ホスト設定](Guides/host-setup.md)が必要です。```shvphone-cli vm create myphone \@@ -22,7 +22,7 @@ vphone-cli vm launch myphone`vm create` は準備、JB パッチ、DFU 復元、CFW インストールを実行し、初回起動で vphoned に ping します。**確認用の起動は成功後に停止します。** 継続して使うには `vm launch` を実行してください。復元にはネットワーク接続、CFW インストールには管理者認証が必要です。-cloudOS 26.4(`23E5207q`)との組み合わせで、iPhone17,3 の iOS 26.6.2(`23G90`)と 27.0(`24A435`)がロック画面に到達し、vphoned ping に応答しました。詳細は[互換性の記録](guides/compatibility.md)を参照してください。+cloudOS 26.4(`23E5207q`)との組み合わせで、iPhone17,3 の iOS 26.6.2(`23G90`)と 27.0(`24A435`)がロック画面に到達し、vphoned ping に応答しました。詳細は[互換性の記録](Guides/compatibility.md)を参照してください。## インストールとビルド@@ -35,4 +35,4 @@ zsh Scripts/build.sh.build/release/vphone-cli host preflight```-AMFI の許可リストを使う場合、ビルドのたびに[ホストの設定手順](guides/host-setup.md)に従って署名済み VM バイナリを再登録してください。[ドキュメント一覧](README.md)から現在の手順と研究資料に進めます。詳しいガイドは現在英語です。+AMFI の許可リストを使う場合、ビルドのたびに[ホストの設定手順](Guides/host-setup.md)に従って署名済み VM バイナリを再登録してください。[ドキュメント一覧](README.md)から現在の手順と研究資料に進めます。詳しいガイドは現在英語です。diff --git a/docs/README_ko.md b/Documents/README_ko.mdsimilarity index 91%rename from docs/README_ko.mdrename to Documents/README_ko.mdindex d94bee41..a89cb140 100644--- a/docs/README_ko.md+++ b/Documents/README_ko.md@@ -10,7 +10,7 @@ Apple Virtualization.framework와 PCC 연구용 VM 기반으로 가상 iPhone을## 빠른 시작-Apple Silicon Mac, macOS 15 이상, 그리고 PV=3 연구용 VM과 `vphone-vm` 권한을 허용하는 [호스트 설정](guides/host-setup.md)이 필요합니다.+Apple Silicon Mac, macOS 15 이상, 그리고 PV=3 연구용 VM과 `vphone-vm` 권한을 허용하는 [호스트 설정](Guides/host-setup.md)이 필요합니다.```shvphone-cli vm create myphone \@@ -22,7 +22,7 @@ vphone-cli vm launch myphone`vm create`는 준비, JB 패치, DFU 복원, CFW 설치를 수행하고 첫 부팅에서 vphoned에 실제로 ping합니다. **검증용 부팅은 성공 후 종료됩니다.** 계속 사용하려면 `vm launch`를 실행하세요. 복원에는 네트워크가, CFW 설치에는 관리자 인증이 필요합니다.-cloudOS 26.4(`23E5207q`)와 함께 iPhone17,3 iOS 26.6.2(`23G90`), 27.0(`24A435`)이 잠금 화면에 도달하고 vphoned ping에 응답했습니다. 범위는 [호환성 기록](guides/compatibility.md)을 참고하세요.+cloudOS 26.4(`23E5207q`)와 함께 iPhone17,3 iOS 26.6.2(`23G90`), 27.0(`24A435`)이 잠금 화면에 도달하고 vphoned ping에 응답했습니다. 범위는 [호환성 기록](Guides/compatibility.md)을 참고하세요.## 설치와 빌드@@ -35,4 +35,4 @@ zsh Scripts/build.sh.build/release/vphone-cli host preflight```-AMFI 허용 목록을 사용하는 호스트에서는 빌드할 때마다 [호스트 설정 가이드](guides/host-setup.md)에 따라 서명된 VM 바이너리를 다시 허용하세요. 현재 가이드와 연구 자료는 [문서 목차](README.md)에 모았습니다. 상세 가이드는 현재 영어로 제공됩니다.+AMFI 허용 목록을 사용하는 호스트에서는 빌드할 때마다 [호스트 설정 가이드](Guides/host-setup.md)에 따라 서명된 VM 바이너리를 다시 허용하세요. 현재 가이드와 연구 자료는 [문서 목차](README.md)에 모았습니다. 상세 가이드는 현재 영어로 제공됩니다.diff --git a/docs/README_zh.md b/Documents/README_zh.mdsimilarity index 88%rename from docs/README_zh.mdrename to Documents/README_zh.mdindex 16a85d10..b107f7ae 100644--- a/docs/README_zh.md+++ b/Documents/README_zh.md@@ -10,7 +10,7 @@## 快速开始-需要 Apple Silicon Mac、macOS 15 或更新版本,以及允许 PV=3 研究虚拟机和 `vphone-vm` 私有授权的宿主机设置。先看[宿主机准备](guides/host-setup.md)。+需要 Apple Silicon Mac、macOS 15 或更新版本,以及允许 PV=3 研究虚拟机和 `vphone-vm` 私有授权的宿主机设置。先看[宿主机准备](Guides/host-setup.md)。```shvphone-cli vm create myphone \@@ -22,7 +22,7 @@ vphone-cli vm launch myphone`vm create` 会完成固件准备、JB 补丁、DFU 恢复、CFW 安装,并在首次启动时真正 ping 一次 vphoned。**验收成功后,它会关闭这次临时启动**;要继续使用,请再执行 `vm launch`。恢复阶段需要网络,CFW 安装需要管理员认证。两个 VM 请依次创建,避免磁盘与内存占用叠加。-已用 cloudOS 26.4(`23E5207q`)验证 iPhone17,3 的 iOS 26.6.2(`23G90`)和 27.0(`24A435`):两者都到达锁屏并收到 vphoned ping。其他组合请看[兼容性记录](guides/compatibility.md),不要把它们视为已完成同等验收。+已用 cloudOS 26.4(`23E5207q`)验证 iPhone17,3 的 iOS 26.6.2(`23G90`)和 27.0(`24A435`):两者都到达锁屏并收到 vphoned ping。其他组合请看[兼容性记录](Guides/compatibility.md),不要把它们视为已完成同等验收。## 安装与构建@@ -35,7 +35,7 @@ zsh Scripts/build.sh.build/release/vphone-cli host preflight```-采用 AMFI 白名单的宿主机,每次重编译后都要按[宿主机准备](guides/host-setup.md)中的步骤重新允许签名后的 VM 程序。+采用 AMFI 白名单的宿主机,每次重编译后都要按[宿主机准备](Guides/host-setup.md)中的步骤重新允许签名后的 VM 程序。## 常用命令@@ -48,4 +48,4 @@ zsh Scripts/build.sh| 导入备份 | `vphone-cli vm import myphone.tzst --name restored` || 查看固件配对 | `vphone-cli fw catalog` |-虚拟机和固件缓存默认位于 `~/.vphone/`。完整步骤、手动流水线和存储路径见[创建与运行指南](guides/create-and-run.md)。[文档目录](README.md)汇总其余指南;[研究目录](../research/README.md)收录补丁与实现记录。详细指南目前以英文为准。+虚拟机和固件缓存默认位于 `~/.vphone/`。完整步骤、手动流水线和存储路径见[创建与运行指南](Guides/create-and-run.md)。[文档目录](README.md)汇总其余指南;[研究目录](../Research/README.md)收录补丁与实现记录。详细指南目前以英文为准。diff --git a/docs/demo.jpeg b/Documents/demo.jpegsimilarity index 100%rename from docs/demo.jpegrename to Documents/demo.jpegdiff --git a/README.md b/README.mdindex 6fe0c8ed..bc5be801 100644--- a/README.md+++ b/README.md@@ -1,16 +1,16 @@-<div align="right"><strong>English</strong> · <a href="docs/README_zh.md">中文</a> · <a href="docs/README_ja.md">日本語</a> · <a href="docs/README_ko.md">한국어</a></div>+<div align="right"><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># vphone-cliBoot a virtual iPhone with Apple's Virtualization.framework and PCC research VM infrastructure.-+The supported firmware flow is **JB only**. It applies the required system patches and installs **vphoned** for host control. It leaves the guest user environment alone: no package manager, SSH server, VNC server, or first-boot bootstrap is installed.## Quick start-Use an Apple Silicon Mac running macOS 15 or newer. The host must permit PV=3 research guests and the private entitlements on `vphone-vm`; see [host setup](docs/guides/host-setup.md) before the first boot. A Mac running inside another VM cannot boot this guest.+Use an Apple Silicon Mac running macOS 15 or newer. The host must permit PV=3 research guests and the private entitlements on `vphone-vm`; see [host setup](Documents/Guides/host-setup.md) before the first boot. A Mac running inside another VM cannot boot this guest.```shvphone-cli vm create myphone \@@ -27,12 +27,12 @@ app using `VPhoneAPIKit`, opt in when launching:vphone-cli vm launch myphone --api-listen 127.0.0.1:8765```-The guest runs `icli` commands through the API. See the [API design and usage](research/vphoned_http_api.md)+The guest runs `icli` commands through the API. See the [API design and usage](Research/vphoned_http_api.md)for routes, WebSocket messages, and the Swift Kit client.`vm create` prepares and patches firmware, restores the VM, installs the JB system changes and vphoned, then boots once to check a real vphoned ping. **It stops that verification boot before returning.** Run `vm launch` to keep using the VM. The create flow needs network access for Apple's restore ticket and asks for administrator authentication during CFW installation.-For local validation, iPhone17,3 **26.6.2 (23G90)** and **27.0 (24A435)** both reached the lock screen and answered vphoned ping with cloudOS **26.4 (23E5207q)**. See [compatibility and evidence](docs/guides/compatibility.md); other firmware combinations are not implied by these results.+For local validation, iPhone17,3 **26.6.2 (23G90)** and **27.0 (24A435)** both reached the lock screen and answered vphoned ping with cloudOS **26.4 (23E5207q)**. See [compatibility and evidence](Documents/Guides/compatibility.md); other firmware combinations are not implied by these results.## Install or build@@ -47,7 +47,7 @@ zsh Scripts/build.sh.build/release/vphone-cli --help```-`Scripts/build.sh` builds, signs, and bundles the binaries. Run `swift test` for the Swift tests and `zsh Scripts/check_aux.sh` for the bundle checks. After every rebuild, a host using the AMFI allowlist must allow the new signed binaries because their cdhashes change. See [host setup](docs/guides/host-setup.md).+`Scripts/build.sh` builds, signs, and bundles the binaries. Run `swift test` for the Swift tests and `zsh Scripts/check_aux.sh` for the bundle checks. After every rebuild, a host using the AMFI allowlist must allow the new signed binaries because their cdhashes change. See [host setup](Documents/Guides/host-setup.md).## Everyday commands@@ -66,10 +66,10 @@ VMs and downloaded firmware live under `~/.vphone/` by default. `VPHONE_ROOT` re## Documentation-- [Documentation index](docs/README.md) — setup, workflows, compatibility, troubleshooting, and translations.-- [Create and run a VM](docs/guides/create-and-run.md) — full flow, manual stages, storage, and vphoned.-- [Research index](research/README.md) — patch inventory, firmware analysis, restore work, and historical notes.-- [Patch inventory](research/0_binary_patch_comparison.md) — per-component patch breakdown and historical variant comparison. Only JB is exposed by the current CLI.+- [Documentation index](Documents/README.md) — setup, workflows, compatibility, troubleshooting, and translations.+- [Create and run a VM](Documents/Guides/create-and-run.md) — full flow, manual stages, storage, and vphoned.+- [Research index](Research/README.md) — patch inventory, firmware analysis, restore work, and historical notes.+- [Patch inventory](Research/0_binary_patch_comparison.md) — per-component patch breakdown and historical variant comparison. Only JB is exposed by the current CLI.## Acknowledgementsdiff --git a/research/0_binary_patch_comparison.md b/Research/0_binary_patch_comparison.mdsimilarity index 100%rename from research/0_binary_patch_comparison.mdrename to Research/0_binary_patch_comparison.mddiff --git a/research/firmware/firmware_manifest_and_origins.md b/Research/Firmware/firmware_manifest_and_origins.mdsimilarity index 100%rename from research/firmware/firmware_manifest_and_origins.mdrename to Research/Firmware/firmware_manifest_and_origins.mddiff --git a/research/firmware/iboot_patches.md b/Research/Firmware/iboot_patches.mdsimilarity index 100%rename from research/firmware/iboot_patches.mdrename to Research/Firmware/iboot_patches.mddiff --git a/research/firmware/txm_fullchain_analysis.md b/Research/Firmware/txm_fullchain_analysis.mdsimilarity index 100%rename from research/firmware/txm_fullchain_analysis.mdrename to Research/Firmware/txm_fullchain_analysis.mddiff --git a/research/firmware/txm_jb_patches.md b/Research/Firmware/txm_jb_patches.mdsimilarity index 100%rename from research/firmware/txm_jb_patches.mdrename to Research/Firmware/txm_jb_patches.mddiff --git a/research/firmware/txm_selector24_analysis.md b/Research/Firmware/txm_selector24_analysis.mdsimilarity index 100%rename from research/firmware/txm_selector24_analysis.mdrename to Research/Firmware/txm_selector24_analysis.mddiff --git a/research/firmware/txm_variant_diff.md b/Research/Firmware/txm_variant_diff.mdsimilarity index 100%rename from research/firmware/txm_variant_diff.mdrename to Research/Firmware/txm_variant_diff.mddiff --git a/research/guest/devmode_xpc_protocol.md b/Research/Guest/devmode_xpc_protocol.mdsimilarity index 100%rename from research/guest/devmode_xpc_protocol.mdrename to Research/Guest/devmode_xpc_protocol.mddiff --git a/research/guest/keyboard_event_pipeline.md b/Research/Guest/keyboard_event_pipeline.mdsimilarity index 100%rename from research/guest/keyboard_event_pipeline.mdrename to Research/Guest/keyboard_event_pipeline.mddiff --git a/research/guest/machine_identifier_storage_analysis.md b/Research/Guest/machine_identifier_storage_analysis.mdsimilarity index 100%rename from research/guest/machine_identifier_storage_analysis.mdrename to Research/Guest/machine_identifier_storage_analysis.mddiff --git a/research/history/intg_update_status.md b/Research/History/intg_update_status.mdsimilarity index 99%rename from research/history/intg_update_status.mdrename to Research/History/intg_update_status.mdindex 67b9fbe4..e16b3fa8 100644--- a/research/history/intg_update_status.md+++ b/Research/History/intg_update_status.md@@ -20,7 +20,7 @@>> **Updated at `a908f81`**, after D2 and D3 landed. The D2/D3 rows below are> rewritten; the D4 row is not, and the detail is in-> [`d2_d3_self_containment.md`](../host/d2_d3_self_containment.md), which is the+> [`d2_d3_self_containment.md`](../Host/d2_d3_self_containment.md), which is the> handover for that work — what the tiers are, what each removed program was> replaced by, what was verified against the real tool, and what is left open.@@ -52,7 +52,7 @@ is 2,396 lines against 2,410 at the branch base.| P0.5 | `VPhoneArchive` + `vphone-archive` | ✅ library, binary, tests, fingerprint tool || P0.5 | switch the archive call sites | ✅ **done at `356bec6`.** `$TAR` is gone from `cfw_install*.sh`; only `cfw-kit` still finds `gtar`, and it is build tier and does not ship || P0.5 | `VPhoneSign`, drop `ldid` | ✅ **done at `356bec6`.** The installers and the Makefile call `vphone-cli sign`; nothing looks `ldid` up any more except `cfw-kit` |-| P0.5 | admission gates | ✅ **`make check-aux`, six gates, all green, dist list empty** — see [`d2_d3_self_containment.md`](../host/d2_d3_self_containment.md) |+| P0.5 | admission gates | ✅ **`make check-aux`, six gates, all green, dist list empty** — see [`d2_d3_self_containment.md`](../Host/d2_d3_self_containment.md) || **P1.0–1.5** | CFW patchers | ✅ **complete** — `scripts/patchers/` deleted at `d90371a`, 26 files / 6,539 lines into 24 `vphone-cli cfw` verbs || **P2.0** | can libirecovery see the virtual DFU endpoint? | ✅ **yes** — `research/restore/p2_dfu_spike.md` || **P2.1–2.2** | vendor libirecovery + idevicerestore | ✅ `Sources/MobileRecoveryCore`, `Sources/MobileRestoreCore` |@@ -112,7 +112,7 @@ Two corrections to the earlier ledger's arithmetic:>> **Now**: `zsh Scripts/check_aux.sh` reports gates 0, 1, 1b, 1c, 2 and 3 all> green, with the **dist tier's registered list empty**. See-> [`d2_d3_self_containment.md`](../host/d2_d3_self_containment.md).+> [`d2_d3_self_containment.md`](../Host/d2_d3_self_containment.md).`zsh Scripts/check_aux.sh --fast`, as of the previous revision:diff --git a/research/history/manifest_and_refactoring_summary.md b/Research/History/manifest_and_refactoring_summary.mdsimilarity index 99%rename from research/history/manifest_and_refactoring_summary.mdrename to Research/History/manifest_and_refactoring_summary.mdindex 11175885..bf8bd75e 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](../../docs/guides/create-and-run.md)+> by the native Swift workflow. See the [current VM guide](../../Documents/Guides/create-and-run.md)> and [research index](../README.md).## Summarydiff --git a/research/host/archive_extraction_contracts.md b/Research/Host/archive_extraction_contracts.mdsimilarity index 100%rename from research/host/archive_extraction_contracts.mdrename to Research/Host/archive_extraction_contracts.mddiff --git a/research/host/d2_d3_self_containment.md b/Research/Host/d2_d3_self_containment.mdsimilarity index 100%rename from research/host/d2_d3_self_containment.mdrename to Research/Host/d2_d3_self_containment.mddiff --git a/research/host/host_binary_split.md b/Research/Host/host_binary_split.mdsimilarity index 100%rename from research/host/host_binary_split.mdrename to Research/Host/host_binary_split.mddiff --git a/research/host/libarchive_xcframework_validation.md b/Research/Host/libarchive_xcframework_validation.mdsimilarity index 100%rename from research/host/libarchive_xcframework_validation.mdrename to Research/Host/libarchive_xcframework_validation.mddiff --git a/research/host/naming_and_shared_module_review.md b/Research/Host/naming_and_shared_module_review.mdsimilarity index 100%rename from research/host/naming_and_shared_module_review.mdrename to Research/Host/naming_and_shared_module_review.mddiff --git a/research/kernel/kernel_fairplay_kexts.md b/Research/Kernel/kernel_fairplay_kexts.mdsimilarity index 100%rename from research/kernel/kernel_fairplay_kexts.mdrename to Research/Kernel/kernel_fairplay_kexts.mddiff --git a/research/kernel/kernel_jb_patch_notes.md b/Research/Kernel/kernel_jb_patch_notes.mdsimilarity index 100%rename from research/kernel/kernel_jb_patch_notes.mdrename to Research/Kernel/kernel_jb_patch_notes.mddiff --git a/research/kernel/kernel_patch_base_11_15_validation.md b/Research/Kernel/kernel_patch_base_11_15_validation.mdsimilarity index 100%rename from research/kernel/kernel_patch_base_11_15_validation.mdrename to Research/Kernel/kernel_patch_base_11_15_validation.mddiff --git a/research/kernel/kernel_patch_base_16_20_validation.md b/Research/Kernel/kernel_patch_base_16_20_validation.mdsimilarity index 100%rename from research/kernel/kernel_patch_base_16_20_validation.mdrename to Research/Kernel/kernel_patch_base_16_20_validation.mddiff --git a/research/kernel/kernel_patch_base_first5_validation.md b/Research/Kernel/kernel_patch_base_first5_validation.mdsimilarity index 100%rename from research/kernel/kernel_patch_base_first5_validation.mdrename to Research/Kernel/kernel_patch_base_first5_validation.mddiff --git a/research/kernel/kernel_patch_sandbox_hooks_17_26_validation.md b/Research/Kernel/kernel_patch_sandbox_hooks_17_26_validation.mdsimilarity index 100%rename from research/kernel/kernel_patch_sandbox_hooks_17_26_validation.mdrename to Research/Kernel/kernel_patch_sandbox_hooks_17_26_validation.mddiff --git a/research/kernel/kernel_patcher_verification.md b/Research/Kernel/kernel_patcher_verification.mdsimilarity index 100%rename from research/kernel/kernel_patcher_verification.mdrename to Research/Kernel/kernel_patcher_verification.mddiff --git a/research/kernel_jailbreak_patches/26.5_jb_hook_fixes.md b/Research/KernelJailbreakPatches/26.5_jb_hook_fixes.mdsimilarity index 100%rename from research/kernel_jailbreak_patches/26.5_jb_hook_fixes.mdrename to Research/KernelJailbreakPatches/26.5_jb_hook_fixes.mddiff --git a/research/kernel_jailbreak_patches/PATCH_DOC_FRAMEWORK.md b/Research/KernelJailbreakPatches/PATCH_DOC_FRAMEWORK.mdsimilarity index 100%rename from research/kernel_jailbreak_patches/PATCH_DOC_FRAMEWORK.mdrename to Research/KernelJailbreakPatches/PATCH_DOC_FRAMEWORK.mddiff --git a/research/kernel_jailbreak_patches/README.md b/Research/KernelJailbreakPatches/README.mdsimilarity index 92%rename from research/kernel_jailbreak_patches/README.mdrename to Research/KernelJailbreakPatches/README.mdindex 27aa31f9..32d19ae9 100644--- a/research/kernel_jailbreak_patches/README.md+++ b/Research/KernelJailbreakPatches/README.md@@ -11,6 +11,6 @@ These notes explain the source anchors, binary matches and validation evidence f| Tasks, ports and threads | [convert port to map](patch_convert_port_to_map.md), [task conversion](patch_task_conversion_eval_internal.md), [task for PID](patch_task_for_pid.md), [thread set state](patch_thread_set_state.md), [thread crash gate](patch_thid_should_crash.md) || VM and shared regions | [VM fault](patch_vm_fault_enter_prepare.md), [immutable map delete](patch_vm_map_delete_immutable_code.md), [VM map protect](patch_vm_map_protect.md), [shared region map](patch_shared_region_map.md) || 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](runtime_verification/README.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](../../docs/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/Guides/create-and-run.md).diff --git a/research/kernel_jailbreak_patches/runtime_verification/README.md b/Research/KernelJailbreakPatches/RuntimeVerification/README.mdsimilarity index 96%rename from research/kernel_jailbreak_patches/runtime_verification/README.mdrename to Research/KernelJailbreakPatches/RuntimeVerification/README.mdindex 1f51ca38..354d51cd 100644--- a/research/kernel_jailbreak_patches/runtime_verification/README.md+++ b/Research/KernelJailbreakPatches/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](../../../docs/guides/create-and-run.md) and+> [VM guide](../../../Documents/Guides/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/kernel_jailbreak_patches/runtime_verification/ida_patch_chain_report.md b/Research/KernelJailbreakPatches/RuntimeVerification/ida_patch_chain_report.mdsimilarity index 100%rename from research/kernel_jailbreak_patches/runtime_verification/ida_patch_chain_report.mdrename to Research/KernelJailbreakPatches/RuntimeVerification/ida_patch_chain_report.mddiff --git a/research/kernel_jailbreak_patches/runtime_verification/runtime_verification_summary.md b/Research/KernelJailbreakPatches/RuntimeVerification/runtime_verification_summary.mdsimilarity index 100%rename from research/kernel_jailbreak_patches/runtime_verification/runtime_verification_summary.mdrename to Research/KernelJailbreakPatches/RuntimeVerification/runtime_verification_summary.mddiff --git a/research/kernel_jailbreak_patches/patch_amfi_cdhash_in_trustcache.md b/Research/KernelJailbreakPatches/patch_amfi_cdhash_in_trustcache.mdsimilarity index 100%rename from research/kernel_jailbreak_patches/patch_amfi_cdhash_in_trustcache.mdrename to Research/KernelJailbreakPatches/patch_amfi_cdhash_in_trustcache.mddiff --git a/research/kernel_jailbreak_patches/patch_amfi_execve_kill_path.md b/Research/KernelJailbreakPatches/patch_amfi_execve_kill_path.mdsimilarity index 100%rename from research/kernel_jailbreak_patches/patch_amfi_execve_kill_path.mdrename to Research/KernelJailbreakPatches/patch_amfi_execve_kill_path.mddiff --git a/research/kernel_jailbreak_patches/patch_bsd_init_auth.md b/Research/KernelJailbreakPatches/patch_bsd_init_auth.mdsimilarity index 100%rename from research/kernel_jailbreak_patches/patch_bsd_init_auth.mdrename to Research/KernelJailbreakPatches/patch_bsd_init_auth.mddiff --git a/research/kernel_jailbreak_patches/patch_convert_port_to_map.md b/Research/KernelJailbreakPatches/patch_convert_port_to_map.mdsimilarity index 100%rename from research/kernel_jailbreak_patches/patch_convert_port_to_map.mdrename to Research/KernelJailbreakPatches/patch_convert_port_to_map.mddiff --git a/research/kernel_jailbreak_patches/patch_cred_label_update_execve.md b/Research/KernelJailbreakPatches/patch_cred_label_update_execve.mdsimilarity index 100%rename from research/kernel_jailbreak_patches/patch_cred_label_update_execve.mdrename to Research/KernelJailbreakPatches/patch_cred_label_update_execve.mddiff --git a/research/kernel_jailbreak_patches/patch_dounmount.md b/Research/KernelJailbreakPatches/patch_dounmount.mdsimilarity index 100%rename from research/kernel_jailbreak_patches/patch_dounmount.mdrename to Research/KernelJailbreakPatches/patch_dounmount.mddiff --git a/research/kernel_jailbreak_patches/patch_hook_cred_label_update_execve.md b/Research/KernelJailbreakPatches/patch_hook_cred_label_update_execve.mdsimilarity index 100%rename from research/kernel_jailbreak_patches/patch_hook_cred_label_update_execve.mdrename to Research/KernelJailbreakPatches/patch_hook_cred_label_update_execve.mddiff --git a/research/kernel_jailbreak_patches/patch_io_secure_bsd_root.md b/Research/KernelJailbreakPatches/patch_io_secure_bsd_root.mdsimilarity index 100%rename from research/kernel_jailbreak_patches/patch_io_secure_bsd_root.mdrename to Research/KernelJailbreakPatches/patch_io_secure_bsd_root.mddiff --git a/research/kernel_jailbreak_patches/patch_iouc_failed_macf.md b/Research/KernelJailbreakPatches/patch_iouc_failed_macf.mdsimilarity index 100%rename from research/kernel_jailbreak_patches/patch_iouc_failed_macf.mdrename to Research/KernelJailbreakPatches/patch_iouc_failed_macf.mddiff --git a/research/kernel_jailbreak_patches/patch_kcall10.md b/Research/KernelJailbreakPatches/patch_kcall10.mdsimilarity index 100%rename from research/kernel_jailbreak_patches/patch_kcall10.mdrename to Research/KernelJailbreakPatches/patch_kcall10.mddiff --git a/research/kernel_jailbreak_patches/patch_load_dylinker.md b/Research/KernelJailbreakPatches/patch_load_dylinker.mdsimilarity index 100%rename from research/kernel_jailbreak_patches/patch_load_dylinker.mdrename to Research/KernelJailbreakPatches/patch_load_dylinker.mddiff --git a/research/kernel_jailbreak_patches/patch_mac_mount.md b/Research/KernelJailbreakPatches/patch_mac_mount.mdsimilarity index 100%rename from research/kernel_jailbreak_patches/patch_mac_mount.mdrename to Research/KernelJailbreakPatches/patch_mac_mount.mddiff --git a/research/kernel_jailbreak_patches/patch_nvram_verify_permission.md b/Research/KernelJailbreakPatches/patch_nvram_verify_permission.mdsimilarity index 100%rename from research/kernel_jailbreak_patches/patch_nvram_verify_permission.mdrename to Research/KernelJailbreakPatches/patch_nvram_verify_permission.mddiff --git a/research/kernel_jailbreak_patches/patch_post_validation_additional.md b/Research/KernelJailbreakPatches/patch_post_validation_additional.mdsimilarity index 100%rename from research/kernel_jailbreak_patches/patch_post_validation_additional.mdrename to Research/KernelJailbreakPatches/patch_post_validation_additional.mddiff --git a/research/kernel_jailbreak_patches/patch_proc_pidinfo.md b/Research/KernelJailbreakPatches/patch_proc_pidinfo.mdsimilarity index 100%rename from research/kernel_jailbreak_patches/patch_proc_pidinfo.mdrename to Research/KernelJailbreakPatches/patch_proc_pidinfo.mddiff --git a/research/kernel_jailbreak_patches/patch_proc_security_policy.md b/Research/KernelJailbreakPatches/patch_proc_security_policy.mdsimilarity index 100%rename from research/kernel_jailbreak_patches/patch_proc_security_policy.mdrename to Research/KernelJailbreakPatches/patch_proc_security_policy.mddiff --git a/research/kernel_jailbreak_patches/patch_sandbox_hooks_extended.md b/Research/KernelJailbreakPatches/patch_sandbox_hooks_extended.mdsimilarity index 100%rename from research/kernel_jailbreak_patches/patch_sandbox_hooks_extended.mdrename to Research/KernelJailbreakPatches/patch_sandbox_hooks_extended.mddiff --git a/research/kernel_jailbreak_patches/patch_shared_region_map.md b/Research/KernelJailbreakPatches/patch_shared_region_map.mdsimilarity index 100%rename from research/kernel_jailbreak_patches/patch_shared_region_map.mdrename to Research/KernelJailbreakPatches/patch_shared_region_map.mddiff --git a/research/kernel_jailbreak_patches/patch_spawn_validate_persona.md b/Research/KernelJailbreakPatches/patch_spawn_validate_persona.mdsimilarity index 100%rename from research/kernel_jailbreak_patches/patch_spawn_validate_persona.mdrename to Research/KernelJailbreakPatches/patch_spawn_validate_persona.mddiff --git a/research/kernel_jailbreak_patches/patch_syscallmask_apply_to_proc.md b/Research/KernelJailbreakPatches/patch_syscallmask_apply_to_proc.mdsimilarity index 100%rename from research/kernel_jailbreak_patches/patch_syscallmask_apply_to_proc.mdrename to Research/KernelJailbreakPatches/patch_syscallmask_apply_to_proc.mddiff --git a/research/kernel_jailbreak_patches/patch_task_conversion_eval_internal.md b/Research/KernelJailbreakPatches/patch_task_conversion_eval_internal.mdsimilarity index 100%rename from research/kernel_jailbreak_patches/patch_task_conversion_eval_internal.mdrename to Research/KernelJailbreakPatches/patch_task_conversion_eval_internal.mddiff --git a/research/kernel_jailbreak_patches/patch_task_for_pid.md b/Research/KernelJailbreakPatches/patch_task_for_pid.mdsimilarity index 100%rename from research/kernel_jailbreak_patches/patch_task_for_pid.mdrename to Research/KernelJailbreakPatches/patch_task_for_pid.mddiff --git a/research/kernel_jailbreak_patches/patch_thid_should_crash.md b/Research/KernelJailbreakPatches/patch_thid_should_crash.mdsimilarity index 100%rename from research/kernel_jailbreak_patches/patch_thid_should_crash.mdrename to Research/KernelJailbreakPatches/patch_thid_should_crash.mddiff --git a/research/kernel_jailbreak_patches/patch_thread_set_state.md b/Research/KernelJailbreakPatches/patch_thread_set_state.mdsimilarity index 100%rename from research/kernel_jailbreak_patches/patch_thread_set_state.mdrename to Research/KernelJailbreakPatches/patch_thread_set_state.mddiff --git a/research/kernel_jailbreak_patches/patch_vm_fault_enter_prepare.md b/Research/KernelJailbreakPatches/patch_vm_fault_enter_prepare.mdsimilarity index 100%rename from research/kernel_jailbreak_patches/patch_vm_fault_enter_prepare.mdrename to Research/KernelJailbreakPatches/patch_vm_fault_enter_prepare.mddiff --git a/research/kernel_jailbreak_patches/patch_vm_map_delete_immutable_code.md b/Research/KernelJailbreakPatches/patch_vm_map_delete_immutable_code.mdsimilarity index 100%rename from research/kernel_jailbreak_patches/patch_vm_map_delete_immutable_code.mdrename to Research/KernelJailbreakPatches/patch_vm_map_delete_immutable_code.mddiff --git a/research/kernel_jailbreak_patches/patch_vm_map_protect.md b/Research/KernelJailbreakPatches/patch_vm_map_protect.mdsimilarity index 100%rename from research/kernel_jailbreak_patches/patch_vm_map_protect.mdrename to Research/KernelJailbreakPatches/patch_vm_map_protect.mddiff --git a/research/kernel_symbols/kernel_index.tsv b/Research/KernelSymbols/kernel_index.tsvsimilarity index 100%rename from research/kernel_symbols/kernel_index.tsvrename to Research/KernelSymbols/kernel_index.tsvdiff --git a/research/kernel_symbols/kernel_symbols.db b/Research/KernelSymbols/kernel_symbols.dbsimilarity index 100%rename from research/kernel_symbols/kernel_symbols.dbrename to Research/KernelSymbols/kernel_symbols.dbdiff --git a/research/kernel_symbols/summary.tsv b/Research/KernelSymbols/summary.tsvsimilarity index 100%rename from research/kernel_symbols/summary.tsvrename to Research/KernelSymbols/summary.tsvdiff --git a/research/patches/cfw_patch_launchd_jetsam.md b/Research/Patches/cfw_patch_launchd_jetsam.mdsimilarity index 100%rename from research/patches/cfw_patch_launchd_jetsam.mdrename to Research/Patches/cfw_patch_launchd_jetsam.mddiff --git a/research/patches/hv_vmm_present_usermode_xrefs.md b/Research/Patches/hv_vmm_present_usermode_xrefs.mdsimilarity index 100%rename from research/patches/hv_vmm_present_usermode_xrefs.mdrename to Research/Patches/hv_vmm_present_usermode_xrefs.mddiff --git a/research/patches/patch_reference_capture.md b/Research/Patches/patch_reference_capture.mdsimilarity index 100%rename from research/patches/patch_reference_capture.mdrename to Research/Patches/patch_reference_capture.mddiff --git a/Research/README.md b/Research/README.mdnew file mode 100644index 00000000..821e4416--- /dev/null+++ b/Research/README.md@@ -0,0 +1,26 @@+# Research library++[Project overview](../README.md) · [User documentation](../Documents/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.++## Start here++1. [Patch comparison](0_binary_patch_comparison.md) is the canonical per-component inventory. Its regular/dev/exp columns are historical.+2. [Firmware manifest and origins](Firmware/firmware_manifest_and_origins.md) explains the hybrid firmware inputs.+3. [JB kernel patch notes](Kernel/kernel_jb_patch_notes.md) and the [individual patch index](KernelJailbreakPatches/README.md) lead to the kernel evidence.+4. [Native restore design](Restore/p2_restore_off_python.md) and [self-contained runtime](Host/d2_d3_self_containment.md) explain the host migration.++## By subject++| Subject | Notes |+| --- | --- |+| Firmware and boot chain | [Manifest and origins](Firmware/firmware_manifest_and_origins.md), [iBoot patches](Firmware/iboot_patches.md), [TXM full chain](Firmware/txm_fullchain_analysis.md), [TXM JB patches](Firmware/txm_jb_patches.md), [selector 24](Firmware/txm_selector24_analysis.md), [variant differences](Firmware/txm_variant_diff.md) |+| Kernel | [JB overview](Kernel/kernel_jb_patch_notes.md), [patcher verification](Kernel/kernel_patcher_verification.md), [FairPlay kexts](Kernel/kernel_fairplay_kexts.md), [base validation 1–5](Kernel/kernel_patch_base_first5_validation.md), [11–15](Kernel/kernel_patch_base_11_15_validation.md), [16–20](Kernel/kernel_patch_base_16_20_validation.md), [sandbox hooks](Kernel/kernel_patch_sandbox_hooks_17_26_validation.md), [individual patch notes](KernelJailbreakPatches/README.md) |+| Other patches and captures | [Launchd jetsam](Patches/cfw_patch_launchd_jetsam.md), [user-mode hypervisor references](Patches/hv_vmm_present_usermode_xrefs.md), [reference capture](Patches/patch_reference_capture.md) |+| Restore | [DFU probe](Restore/p2_dfu_spike.md), [in-process restore](Restore/p2_restore_off_python.md) |+| Host and archives | [Binary split](Host/host_binary_split.md), [runtime dependency tiers](Host/d2_d3_self_containment.md), [archive extraction contracts](Host/archive_extraction_contracts.md), [libarchive validation](Host/libarchive_xcframework_validation.md) |+| Guest interaction and VM identity | [DevMode XPC](Guest/devmode_xpc_protocol.md), [keyboard events](Guest/keyboard_event_pipeline.md), [machine identifier](Guest/machine_identifier_storage_analysis.md) |+| Historical project records | [Migration ledger](History/intg_update_status.md), [manifest refactoring summary](History/manifest_and_refactoring_summary.md) |++`KernelSymbols/` holds symbol datasets and indexes; `Reference/` holds source references when present. They are evidence inputs, not steps for running the distributed app. The files in `History/` are preserved snapshots and may describe scripts or variants that have since been removed.diff --git a/research/restore/p2_dfu_spike.md b/Research/Restore/p2_dfu_spike.mdsimilarity index 100%rename from research/restore/p2_dfu_spike.mdrename to Research/Restore/p2_dfu_spike.mddiff --git a/research/restore/p2_restore_off_python.md b/Research/Restore/p2_restore_off_python.mdsimilarity index 100%rename from research/restore/p2_restore_off_python.mdrename to Research/Restore/p2_restore_off_python.mddiff --git a/research/VPhoneVirtualMachineRefactored.swift b/Research/VPhoneVirtualMachineRefactored.swiftsimilarity index 100%rename from research/VPhoneVirtualMachineRefactored.swiftrename to Research/VPhoneVirtualMachineRefactored.swiftdiff --git a/research/hv_vmm_present_xref.json b/Research/hv_vmm_present_xref.jsonsimilarity index 100%rename from research/hv_vmm_present_xref.jsonrename to Research/hv_vmm_present_xref.jsondiff --git a/research/vphoned_http_api.md b/Research/vphoned_http_api.mdsimilarity index 100%rename from research/vphoned_http_api.mdrename to Research/vphoned_http_api.mddiff --git a/Scripts/build.sh b/Scripts/build.shindex 346d420d..40c1ceca 100755--- a/Scripts/build.sh+++ b/Scripts/build.sh@@ -221,7 +221,7 @@ cp -f .build/guest/gpu-compiler-plugin.tar.zst "${RES}/gpu/compiler-plugin.tar.zrm -f "${RES}/README.md"rm -rf "${RES}/docs"mkdir -p "${RES}/docs/guides"-cp -f docs/guides/compatibility.md "${RES}/docs/guides/compatibility.md"+cp -f Documents/Guides/compatibility.md "${RES}/docs/guides/compatibility.md"echo " bundled: scripts/ (dist tier), guest/vphoned, guest/icli, gpu/compiler-plugin.tar.zst, vphoned.signed, compatibility.md"# Re-sign: codesign seals Contents/Resources at sign time, so the earlier@@ -250,4 +250,4 @@ echo " vphoned : .build/vphoned.signed"echo ""echo "Run: ${BINARY} --help"echo "If vphone-vm is killed the moment it launches, amfid refused its entitlements."-echo "Allow the new vphone-vm signatures after each build; see docs/guides/host-setup.md."+echo "Allow the new vphone-vm signatures after each build; see Documents/Guides/host-setup.md."diff --git a/skills/kernel-analysis-vphone600/SKILL.md b/Skills/kernel-analysis-vphone600/SKILL.mdsimilarity index 69%rename from skills/kernel-analysis-vphone600/SKILL.mdrename to Skills/kernel-analysis-vphone600/SKILL.mdindex d6700622..40338e2c 100644--- a/skills/kernel-analysis-vphone600/SKILL.md+++ b/Skills/kernel-analysis-vphone600/SKILL.md@@ -5,26 +5,26 @@ description: Analyze vphone600 kernel artifacts using the local symbol database# Kernel Analysis Vphone600-Use the local `research/kernel_symbols` dataset as the first source of truth for symbol lookup.-Use `research/reference/xnu` as the source-level reference for semantics and structure.+Use the local `Research/KernelSymbols` dataset as the first source of truth for symbol lookup.+Use `Research/Reference/xnu` as the source-level reference for semantics and structure.## Required Paths-- `research/kernel_symbols/kernel_symbols.db`-- `research/kernel_symbols/kernel_index.tsv` (plain-text `kernel_name → json_path` index with `json_sha256`)-- `research/kernel_symbols/json/` — the recovered symbol datasets:+- `Research/KernelSymbols/kernel_symbols.db`+- `Research/KernelSymbols/kernel_index.tsv` (plain-text `kernel_name → json_path` index with `json_sha256`)+- `Research/KernelSymbols/json/` — the recovered symbol datasets:- `kernelcache.release.vphone600.bin.symbols.json`- `kernelcache.research.vphone600.bin.symbols.json`-- `research/reference/xnu`+- `Research/Reference/xnu`The `json_path` column in both the database and `kernel_index.tsv` records the absolute path from symbolication-time and may not match this checkout; resolve the JSON files under `research/kernel_symbols/json/` instead.+time and may not match this checkout; resolve the JSON files under `Research/KernelSymbols/json/` instead.-If `research/reference/xnu` is missing, create it with a shallow clone:+If `Research/Reference/xnu` is missing, create it with a shallow clone:```bash-mkdir -p research/reference-git clone --depth 1 https://github.com/apple-oss-distributions/xnu.git research/reference/xnu+mkdir -p Research/Reference+git clone --depth 1 https://github.com/apple-oss-distributions/xnu.git Research/Reference/xnu```## Workflow@@ -32,7 +32,7 @@ git clone --depth 1 https://github.com/apple-oss-distributions/xnu.git research/1. Confirm scope is `vphone600` only.2. Query `kernel_symbols.db` to select `release` or `research` dataset by name.3. Load the linked JSON symbol file and perform symbol/address lookups.-4. Cross-reference candidate code paths in `research/reference/xnu`.+4. Cross-reference candidate code paths in `Research/Reference/xnu`.5. Report findings with explicit kernel name, symbol path, and address.## Output Rulesdiff --git a/skills/kernel-analysis-vphone600/agents/openai.yaml b/Skills/kernel-analysis-vphone600/agents/openai.yamlsimilarity index 100%rename from skills/kernel-analysis-vphone600/agents/openai.yamlrename to Skills/kernel-analysis-vphone600/agents/openai.yamldiff --git a/Skills/kernel-analysis-vphone600/references/kernel-info-queries.md b/Skills/kernel-analysis-vphone600/references/kernel-info-queries.mdnew file mode 100644index 00000000..2e996e46--- /dev/null+++ b/Skills/kernel-analysis-vphone600/references/kernel-info-queries.md@@ -0,0 +1,40 @@+# Kernel Info Queries++Use these commands from repo root (`vphone-cli`).++## Database Introspection++```bash+sqlite3 Research/KernelSymbols/kernel_symbols.db ".schema kernel_symbols"+sqlite3 Research/KernelSymbols/kernel_symbols.db "select count(*) from kernel_symbols;"+sqlite3 Research/KernelSymbols/kernel_symbols.db "select kernel_name, matched, missed, percent, total from kernel_symbols order by kernel_name;"+sqlite3 Research/KernelSymbols/kernel_symbols.db "select kernel_name, json_path from kernel_symbols order by kernel_name;"+```++## Resolve JSON Path By Kernel Name++```bash+sqlite3 Research/KernelSymbols/kernel_symbols.db \+ "select json_path from kernel_symbols where kernel_name='kernelcache.release.vphone600';"+```++```bash+sqlite3 Research/KernelSymbols/kernel_symbols.db \+ "select json_path from kernel_symbols where kernel_name='kernelcache.research.vphone600';"+```++## Fast Symbol Search++```bash+rg -n 'panic' Research/KernelSymbols/json/kernelcache.release.vphone600.bin.symbols.json+rg -n 'mach_trap' Research/KernelSymbols/json/kernelcache.research.vphone600.bin.symbols.json+rg -n '0xfffffe00' Research/KernelSymbols/json/kernelcache.release.vphone600.bin.symbols.json+```++## Use XNU Source Reference++```bash+rg -n 'function_or_symbol_fragment' Research/Reference/xnu/{bsd,osfmk,iokit,security}+```++Prefer direct source matches in `Research/Reference/xnu` for behavioral explanations.diff --git a/Sources/FirmwarePatcher/CustomFirmware/CustomFirmwareMachLookupExceptions.swift b/Sources/FirmwarePatcher/CustomFirmware/CustomFirmwareMachLookupExceptions.swiftindex 9bfe8e44..c13c2cbf 100644--- a/Sources/FirmwarePatcher/CustomFirmware/CustomFirmwareMachLookupExceptions.swift+++ b/Sources/FirmwarePatcher/CustomFirmware/CustomFirmwareMachLookupExceptions.swift@@ -1,7 +1,7 @@// CustomFirmwareMachLookupExceptions.swift — Campo backboard/frontboard mach-lookups.//// Swift port of scripts/patchers/campo_mach_lookup_exceptions.py (JB-3b).-// See research/0_binary_patch_comparison.md #14.+// See Research/0_binary_patch_comparison.md #14.//// iOS 27's temporary sandbox denies Campo.app the backboard/frontboard// services it needs to put a window on screen. The install step dumpsdiff --git a/Sources/FirmwarePatcher/CustomFirmware/ExecutablePatches/CustomFirmwareCacheLoader.swift b/Sources/FirmwarePatcher/CustomFirmware/ExecutablePatches/CustomFirmwareCacheLoader.swiftindex c1f376b3..dbc27f47 100644--- a/Sources/FirmwarePatcher/CustomFirmware/ExecutablePatches/CustomFirmwareCacheLoader.swift+++ b/Sources/FirmwarePatcher/CustomFirmware/ExecutablePatches/CustomFirmwareCacheLoader.swift@@ -22,7 +22,7 @@// skip and the loader refuses anything but the stock cache. NOP'ing the one// `cbz` makes the unsecure path unconditional, which is what lets a MODIFIED// `/System/Library/xpc/launchd.plist` be loaded — the only reason this patch-// exists (`research/0_binary_patch_comparison.md`, "Allow modified+// exists (`Research/0_binary_patch_comparison.md`, "Allow modified// launchd.plist"). A flavour that does not rewrite `launchd.plist` does not// need it; see `cfw-kit/lib/base_stages.sh:stage_launchd_cache_loader`.//diff --git a/Sources/FirmwarePatcher/CustomFirmware/ExecutablePatches/CustomFirmwareJetsam.swift b/Sources/FirmwarePatcher/CustomFirmware/ExecutablePatches/CustomFirmwareJetsam.swiftindex 150f7777..39698c1e 100644--- a/Sources/FirmwarePatcher/CustomFirmware/ExecutablePatches/CustomFirmwareJetsam.swift+++ b/Sources/FirmwarePatcher/CustomFirmware/ExecutablePatches/CustomFirmwareJetsam.swift@@ -51,7 +51,7 @@// is a live bug in the reference: rewriting the gate drops it out of the// conditional-branch set, so the Python's backward scan walks past it and// patches the *next* branch into the same return block — a second, wrong site-// on a binary that was already correct (`research/patches/patch_reference_capture.md`,+// on a binary that was already correct (`Research/Patches/patch_reference_capture.md`,// "The non-idempotency itself is a separate, pre-existing bug"). The fix has to// live inside the scan, because on a re-run neither implementation picks the// site it patched before. So the scan collects unconditional `b`s into a returndiff --git a/Sources/FirmwarePatcher/DyldSharedCache/Patchers/DyldSharedCacheHypervisorVirtualMachinePatcher.swift b/Sources/FirmwarePatcher/DyldSharedCache/Patchers/DyldSharedCacheHypervisorVirtualMachinePatcher.swiftindex 676fe8fa..e6d66514 100644--- a/Sources/FirmwarePatcher/DyldSharedCache/Patchers/DyldSharedCacheHypervisorVirtualMachinePatcher.swift+++ b/Sources/FirmwarePatcher/DyldSharedCache/Patchers/DyldSharedCacheHypervisorVirtualMachinePatcher.swift@@ -497,7 +497,7 @@ public enum DyldSharedCacheHypervisorVirtualMachinePatcher {// dedicated two-instruction patch instead. It is here because it is the rest// of the module this file ports, it is the only way to check the cstring// definition above against a real Mach-O, and the EXP rootfs list in- // `research/0_binary_patch_comparison.md` still names six files it applies+ // `Research/0_binary_patch_comparison.md` still names six files it applies// to./// Mangle every cstring site in the Mach-O at `url`.diff --git a/Sources/FirmwarePatcher/DyldSharedCache/Patchers/DyldSharedCacheMaxSlidePatcher.swift b/Sources/FirmwarePatcher/DyldSharedCache/Patchers/DyldSharedCacheMaxSlidePatcher.swiftindex 8e9e25c6..e8f39f94 100644--- a/Sources/FirmwarePatcher/DyldSharedCache/Patchers/DyldSharedCacheMaxSlidePatcher.swift+++ b/Sources/FirmwarePatcher/DyldSharedCache/Patchers/DyldSharedCacheMaxSlidePatcher.swift@@ -37,7 +37,7 @@// kernel while it is setting the mapping up — not a `cs_validate`'d code page.// The Python reference states the same thing and backs it with a live test: a// cache poked to maxSlide=0 booted with "dyld cache mapped system-wide" and 0-// panics, and `research/0_binary_patch_comparison.md` row 10 records the+// panics, and `Research/0_binary_patch_comparison.md` row 10 records the// on-device validation on `17,3_27.0_24A5380h` + cloudOS 26.4.//// So `DyldSharedCacheCodeSignature.reattestRecordedWrites(in:)` is *not* called here, anddiff --git a/Sources/FirmwarePatcher/DyldSharedCache/Patchers/DyldSharedCacheXPCLWCRPatcher.swift b/Sources/FirmwarePatcher/DyldSharedCache/Patchers/DyldSharedCacheXPCLWCRPatcher.swiftindex 4413910a..007cf833 100644--- a/Sources/FirmwarePatcher/DyldSharedCache/Patchers/DyldSharedCacheXPCLWCRPatcher.swift+++ b/Sources/FirmwarePatcher/DyldSharedCache/Patchers/DyldSharedCacheXPCLWCRPatcher.swift@@ -1,7 +1,7 @@// DyldSharedCacheXPCLWCRPatcher.swift — libxpc's Lightweight Code Requirement self-check.//// Swift port of `scripts/patchers/cfw_patch_xpc_lwcr.py` (`cfw.py-// patch-xpc-lwcr`). See research/0_binary_patch_comparison.md #15.+// patch-xpc-lwcr`). See Research/0_binary_patch_comparison.md #15.//// What breaks// -----------diff --git a/Sources/FirmwarePatcher/Kernel/JailbreakPatches/Frida/KernelJailbreakPatchThreadSetState.swift b/Sources/FirmwarePatcher/Kernel/JailbreakPatches/Frida/KernelJailbreakPatchThreadSetState.swiftindex 23032921..6e690dd3 100644--- a/Sources/FirmwarePatcher/Kernel/JailbreakPatches/Frida/KernelJailbreakPatchThreadSetState.swift+++ b/Sources/FirmwarePatcher/Kernel/JailbreakPatches/Frida/KernelJailbreakPatchThreadSetState.swift@@ -3,7 +3,7 @@// Frida follows an existing thread via thread_set_state_from_user, whose flags// carry TSSF_CHECK_ENTITLEMENT and trip GUARD_TYPE_MACH_PORT. Clear that bit in the// user setters (`mov w6,#0x201` → `mov w6,#0x1`) rather than the check itself.-// Reveal + validation: research/kernel_jailbreak_patches/patch_thread_set_state.md.+// Reveal + validation: Research/KernelJailbreakPatches/patch_thread_set_state.md.import Capstoneimport Foundationdiff --git a/Sources/FirmwarePatcher/Kernel/JailbreakPatches/Frida/KernelJailbreakPatchVmMapDelete.swift b/Sources/FirmwarePatcher/Kernel/JailbreakPatches/Frida/KernelJailbreakPatchVmMapDelete.swiftindex a4720879..d983ad3e 100644--- a/Sources/FirmwarePatcher/Kernel/JailbreakPatches/Frida/KernelJailbreakPatchVmMapDelete.swift+++ b/Sources/FirmwarePatcher/Kernel/JailbreakPatches/Frida/KernelJailbreakPatchVmMapDelete.swift@@ -4,7 +4,7 @@// vm_map_delete's immutable-code exception tests current-protection EXECUTE, which// is clear, so re-instrumentation fails with KERN_PROTECTION_FAILURE. Retarget the// test from current-X (packed [entry,#0x38] bit 9) to max-X (bit 13).-// Reveal + validation: research/kernel_jailbreak_patches/patch_vm_map_delete_immutable_code.md.+// Reveal + validation: Research/KernelJailbreakPatches/patch_vm_map_delete_immutable_code.md.import Capstoneimport Foundationdiff --git a/Sources/VPhoneArchive/VPhoneArchiveWriter.swift b/Sources/VPhoneArchive/VPhoneArchiveWriter.swiftindex 5459c4c5..3459b788 100644--- a/Sources/VPhoneArchive/VPhoneArchiveWriter.swift+++ b/Sources/VPhoneArchive/VPhoneArchiveWriter.swift@@ -64,7 +64,7 @@ public enum VPhoneArchiveWriter {// is worth about 4.8x -- but only above one xz block, roughly// 192 MiB at level 9. A smaller archive gets no benefit, and that// is arithmetic rather than a fault. See- // research/host/libarchive_xcframework_validation.md.+ // Research/Host/libarchive_xcframework_validation.md.try setFilterOption(writer, "xz", "threads", "0")case let .gzip(level):archive_write_add_filter_gzip(writer)diff --git a/Sources/VPhoneCLI/VPhoneFirmwareCLI.swift b/Sources/VPhoneCLI/VPhoneFirmwareCLI.swiftindex bd318f71..f74cf64d 100644--- a/Sources/VPhoneCLI/VPhoneFirmwareCLI.swift+++ b/Sources/VPhoneCLI/VPhoneFirmwareCLI.swift@@ -212,7 +212,9 @@ struct VPhoneFirmwarePrepareCommand: ParsableCommand {func run() throws {let resources = projectRoot.map { VPhoneResources(base: URL(fileURLWithPath: $0)) } ?? .resolve()- let readme = resources.base.appendingPathComponent("docs/guides/compatibility.md").path+ let sourceGuide = resources.base.appendingPathComponent("Documents/Guides/compatibility.md")+ let bundleGuide = resources.base.appendingPathComponent("docs/guides/compatibility.md")+ let readme = FileManager.default.fileExists(atPath: sourceGuide.path) ? sourceGuide.path : bundleGuide.pathlet needsCatalog = list || iphoneVersion != nil || iphoneBuild != nillet urls = if needsCatalog {try vphoneRunBlocking {diff --git a/Sources/VPhoneCore/VPhoneGuestLauncher.swift b/Sources/VPhoneCore/VPhoneGuestLauncher.swiftindex 2b123b0b..55c0e0fa 100644--- a/Sources/VPhoneCore/VPhoneGuestLauncher.swift+++ b/Sources/VPhoneCore/VPhoneGuestLauncher.swift@@ -33,7 +33,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/docs/guides/host-setup.md+ rebuild. See https://github.com/Lakr233/vphone-cli/blob/main/Documents/Guides/host-setup.mdfor host settings."""diff --git a/Tests/VPhoneArchiveTests/BundleTransferTests.swift b/Tests/VPhoneArchiveTests/BundleTransferTests.swiftindex f52d5ac4..801872bf 100644--- a/Tests/VPhoneArchiveTests/BundleTransferTests.swift+++ b/Tests/VPhoneArchiveTests/BundleTransferTests.swift@@ -474,7 +474,7 @@ struct BundleTransferTests {////// gzip rather than zstd only so the check does not need a `zstd(1)` on/// PATH — which is the whole point of the migration. The compressor is- /// detected either way; `research/host/archive_extraction_contracts.md` records+ /// detected either way; `Research/Host/archive_extraction_contracts.md` records/// the .tzst and .txz runs.@Test func `import reads archive written by the old tar pipeline`() throws {let root = try makeRoot()diff --git a/Tests/VPhoneCoreTests/FirmwareMatrixTests.swift b/Tests/VPhoneCoreTests/FirmwareMatrixTests.swiftindex 3dbd2887..8280ca3f 100644--- a/Tests/VPhoneCoreTests/FirmwareMatrixTests.swift+++ b/Tests/VPhoneCoreTests/FirmwareMatrixTests.swift@@ -319,7 +319,7 @@ private enum RealData {.deletingLastPathComponent().deletingLastPathComponent().deletingLastPathComponent()- .appendingPathComponent("docs/guides/compatibility.md")+ .appendingPathComponent("Documents/Guides/compatibility.md")return try String(contentsOf: url, encoding: .utf8)}diff --git a/research/README.md b/research/README.mddeleted file mode 100644index f3a6b587..00000000--- a/research/README.md+++ /dev/null@@ -1,26 +0,0 @@-# Research library--[Project overview](../README.md) · [User documentation](../docs/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](../docs/README.md) and `vphone-cli --help` for current instructions.--## Start here--1. [Patch comparison](0_binary_patch_comparison.md) is the canonical per-component inventory. Its regular/dev/exp columns are historical.-2. [Firmware manifest and origins](firmware/firmware_manifest_and_origins.md) explains the hybrid firmware inputs.-3. [JB kernel patch notes](kernel/kernel_jb_patch_notes.md) and the [individual patch index](kernel_jailbreak_patches/README.md) lead to the kernel evidence.-4. [Native restore design](restore/p2_restore_off_python.md) and [self-contained runtime](host/d2_d3_self_containment.md) explain the host migration.--## By subject--| Subject | Notes |-| --- | --- |-| Firmware and boot chain | [Manifest and origins](firmware/firmware_manifest_and_origins.md), [iBoot patches](firmware/iboot_patches.md), [TXM full chain](firmware/txm_fullchain_analysis.md), [TXM JB patches](firmware/txm_jb_patches.md), [selector 24](firmware/txm_selector24_analysis.md), [variant differences](firmware/txm_variant_diff.md) |-| Kernel | [JB overview](kernel/kernel_jb_patch_notes.md), [patcher verification](kernel/kernel_patcher_verification.md), [FairPlay kexts](kernel/kernel_fairplay_kexts.md), [base validation 1–5](kernel/kernel_patch_base_first5_validation.md), [11–15](kernel/kernel_patch_base_11_15_validation.md), [16–20](kernel/kernel_patch_base_16_20_validation.md), [sandbox hooks](kernel/kernel_patch_sandbox_hooks_17_26_validation.md), [individual patch notes](kernel_jailbreak_patches/README.md) |-| Other patches and captures | [Launchd jetsam](patches/cfw_patch_launchd_jetsam.md), [user-mode hypervisor references](patches/hv_vmm_present_usermode_xrefs.md), [reference capture](patches/patch_reference_capture.md) |-| Restore | [DFU probe](restore/p2_dfu_spike.md), [in-process restore](restore/p2_restore_off_python.md) |-| Host and archives | [Binary split](host/host_binary_split.md), [runtime dependency tiers](host/d2_d3_self_containment.md), [archive extraction contracts](host/archive_extraction_contracts.md), [libarchive validation](host/libarchive_xcframework_validation.md) |-| Guest interaction and VM identity | [DevMode XPC](guest/devmode_xpc_protocol.md), [keyboard events](guest/keyboard_event_pipeline.md), [machine identifier](guest/machine_identifier_storage_analysis.md) |-| Historical project records | [Migration ledger](history/intg_update_status.md), [manifest refactoring summary](history/manifest_and_refactoring_summary.md) |--`kernel_symbols/` holds symbol datasets and indexes; `reference/` holds source references when present. They are evidence inputs, not steps for running the distributed app. The files in `history/` are preserved snapshots and may describe scripts or variants that have since been removed.diff --git a/skills/kernel-analysis-vphone600/references/kernel-info-queries.md b/skills/kernel-analysis-vphone600/references/kernel-info-queries.mddeleted file mode 100644index 4a466481..00000000--- a/skills/kernel-analysis-vphone600/references/kernel-info-queries.md+++ /dev/null@@ -1,40 +0,0 @@-# Kernel Info Queries--Use these commands from repo root (`vphone-cli`).--## Database Introspection--```bash-sqlite3 research/kernel_symbols/kernel_symbols.db ".schema kernel_symbols"-sqlite3 research/kernel_symbols/kernel_symbols.db "select count(*) from kernel_symbols;"-sqlite3 research/kernel_symbols/kernel_symbols.db "select kernel_name, matched, missed, percent, total from kernel_symbols order by kernel_name;"-sqlite3 research/kernel_symbols/kernel_symbols.db "select kernel_name, json_path from kernel_symbols order by kernel_name;"-```--## Resolve JSON Path By Kernel Name--```bash-sqlite3 research/kernel_symbols/kernel_symbols.db \- "select json_path from kernel_symbols where kernel_name='kernelcache.release.vphone600';"-```--```bash-sqlite3 research/kernel_symbols/kernel_symbols.db \- "select json_path from kernel_symbols where kernel_name='kernelcache.research.vphone600';"-```--## Fast Symbol Search--```bash-rg -n 'panic' research/kernel_symbols/json/kernelcache.release.vphone600.bin.symbols.json-rg -n 'mach_trap' research/kernel_symbols/json/kernelcache.research.vphone600.bin.symbols.json-rg -n '0xfffffe00' research/kernel_symbols/json/kernelcache.release.vphone600.bin.symbols.json-```--## Use XNU Source Reference--```bash-rg -n 'function_or_symbol_fragment' research/reference/xnu/{bsd,osfmk,iokit,security}-```--Prefer direct source matches in `research/reference/xnu` for behavioral explanations.