Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

refactor: use PascalCase document folders

Lakre5c51bd5784e
diff --git a/.gitignore b/.gitignore
index 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.md
index 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-manager
bootstrap and first-boot installation are outside this project. Do not add
another 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. The
restore 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 with
everything else. Adding an interpreter back brings with it a provisioning
diff --git a/docs/guides/compatibility.md b/Documents/Guides/compatibility.md
similarity index 97%
rename from docs/guides/compatibility.md
rename to Documents/Guides/compatibility.md
index 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 Environments
diff --git a/docs/guides/create-and-run.md b/Documents/Guides/create-and-run.md
similarity index 100%
rename from docs/guides/create-and-run.md
rename to Documents/Guides/create-and-run.md
diff --git a/docs/guides/host-setup.md b/Documents/Guides/host-setup.md
similarity index 97%
rename from docs/guides/host-setup.md
rename to Documents/Guides/host-setup.md
index 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.md
similarity index 100%
rename from docs/guides/troubleshooting.md
rename to Documents/Guides/troubleshooting.md
diff --git a/docs/README.md b/Documents/README.md
similarity index 67%
rename from docs/README.md
rename to Documents/README.md
index 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.md
similarity index 91%
rename from docs/README_ja.md
rename to Documents/README_ja.md
index 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)が必要です。
```sh
vphone-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.md
similarity index 91%
rename from docs/README_ko.md
rename to Documents/README_ko.md
index 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)이 필요합니다.
```sh
vphone-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.md
similarity index 88%
rename from docs/README_zh.md
rename to Documents/README_zh.md
index 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)。
```sh
vphone-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.jpeg
similarity index 100%
rename from docs/demo.jpeg
rename to Documents/demo.jpeg
diff --git a/README.md b/README.md
index 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-cli
Boot a virtual iPhone with Apple's Virtualization.framework and PCC research VM infrastructure.
-![Virtual iPhone running on macOS](docs/demo.jpeg)
+![Virtual iPhone running on macOS](Documents/demo.jpeg)
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.
```sh
vphone-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.
## Acknowledgements
diff --git a/research/0_binary_patch_comparison.md b/Research/0_binary_patch_comparison.md
similarity index 100%
rename from research/0_binary_patch_comparison.md
rename to Research/0_binary_patch_comparison.md
diff --git a/research/firmware/firmware_manifest_and_origins.md b/Research/Firmware/firmware_manifest_and_origins.md
similarity index 100%
rename from research/firmware/firmware_manifest_and_origins.md
rename to Research/Firmware/firmware_manifest_and_origins.md
diff --git a/research/firmware/iboot_patches.md b/Research/Firmware/iboot_patches.md
similarity index 100%
rename from research/firmware/iboot_patches.md
rename to Research/Firmware/iboot_patches.md
diff --git a/research/firmware/txm_fullchain_analysis.md b/Research/Firmware/txm_fullchain_analysis.md
similarity index 100%
rename from research/firmware/txm_fullchain_analysis.md
rename to Research/Firmware/txm_fullchain_analysis.md
diff --git a/research/firmware/txm_jb_patches.md b/Research/Firmware/txm_jb_patches.md
similarity index 100%
rename from research/firmware/txm_jb_patches.md
rename to Research/Firmware/txm_jb_patches.md
diff --git a/research/firmware/txm_selector24_analysis.md b/Research/Firmware/txm_selector24_analysis.md
similarity index 100%
rename from research/firmware/txm_selector24_analysis.md
rename to Research/Firmware/txm_selector24_analysis.md
diff --git a/research/firmware/txm_variant_diff.md b/Research/Firmware/txm_variant_diff.md
similarity index 100%
rename from research/firmware/txm_variant_diff.md
rename to Research/Firmware/txm_variant_diff.md
diff --git a/research/guest/devmode_xpc_protocol.md b/Research/Guest/devmode_xpc_protocol.md
similarity index 100%
rename from research/guest/devmode_xpc_protocol.md
rename to Research/Guest/devmode_xpc_protocol.md
diff --git a/research/guest/keyboard_event_pipeline.md b/Research/Guest/keyboard_event_pipeline.md
similarity index 100%
rename from research/guest/keyboard_event_pipeline.md
rename to Research/Guest/keyboard_event_pipeline.md
diff --git a/research/guest/machine_identifier_storage_analysis.md b/Research/Guest/machine_identifier_storage_analysis.md
similarity index 100%
rename from research/guest/machine_identifier_storage_analysis.md
rename to Research/Guest/machine_identifier_storage_analysis.md
diff --git a/research/history/intg_update_status.md b/Research/History/intg_update_status.md
similarity index 99%
rename from research/history/intg_update_status.md
rename to Research/History/intg_update_status.md
index 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.md
similarity index 99%
rename from research/history/manifest_and_refactoring_summary.md
rename to Research/History/manifest_and_refactoring_summary.md
index 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).
## Summary
diff --git a/research/host/archive_extraction_contracts.md b/Research/Host/archive_extraction_contracts.md
similarity index 100%
rename from research/host/archive_extraction_contracts.md
rename to Research/Host/archive_extraction_contracts.md
diff --git a/research/host/d2_d3_self_containment.md b/Research/Host/d2_d3_self_containment.md
similarity index 100%
rename from research/host/d2_d3_self_containment.md
rename to Research/Host/d2_d3_self_containment.md
diff --git a/research/host/host_binary_split.md b/Research/Host/host_binary_split.md
similarity index 100%
rename from research/host/host_binary_split.md
rename to Research/Host/host_binary_split.md
diff --git a/research/host/libarchive_xcframework_validation.md b/Research/Host/libarchive_xcframework_validation.md
similarity index 100%
rename from research/host/libarchive_xcframework_validation.md
rename to Research/Host/libarchive_xcframework_validation.md
diff --git a/research/host/naming_and_shared_module_review.md b/Research/Host/naming_and_shared_module_review.md
similarity index 100%
rename from research/host/naming_and_shared_module_review.md
rename to Research/Host/naming_and_shared_module_review.md
diff --git a/research/kernel/kernel_fairplay_kexts.md b/Research/Kernel/kernel_fairplay_kexts.md
similarity index 100%
rename from research/kernel/kernel_fairplay_kexts.md
rename to Research/Kernel/kernel_fairplay_kexts.md
diff --git a/research/kernel/kernel_jb_patch_notes.md b/Research/Kernel/kernel_jb_patch_notes.md
similarity index 100%
rename from research/kernel/kernel_jb_patch_notes.md
rename to Research/Kernel/kernel_jb_patch_notes.md
diff --git a/research/kernel/kernel_patch_base_11_15_validation.md b/Research/Kernel/kernel_patch_base_11_15_validation.md
similarity index 100%
rename from research/kernel/kernel_patch_base_11_15_validation.md
rename to Research/Kernel/kernel_patch_base_11_15_validation.md
diff --git a/research/kernel/kernel_patch_base_16_20_validation.md b/Research/Kernel/kernel_patch_base_16_20_validation.md
similarity index 100%
rename from research/kernel/kernel_patch_base_16_20_validation.md
rename to Research/Kernel/kernel_patch_base_16_20_validation.md
diff --git a/research/kernel/kernel_patch_base_first5_validation.md b/Research/Kernel/kernel_patch_base_first5_validation.md
similarity index 100%
rename from research/kernel/kernel_patch_base_first5_validation.md
rename to Research/Kernel/kernel_patch_base_first5_validation.md
diff --git a/research/kernel/kernel_patch_sandbox_hooks_17_26_validation.md b/Research/Kernel/kernel_patch_sandbox_hooks_17_26_validation.md
similarity index 100%
rename from research/kernel/kernel_patch_sandbox_hooks_17_26_validation.md
rename to Research/Kernel/kernel_patch_sandbox_hooks_17_26_validation.md
diff --git a/research/kernel/kernel_patcher_verification.md b/Research/Kernel/kernel_patcher_verification.md
similarity index 100%
rename from research/kernel/kernel_patcher_verification.md
rename to Research/Kernel/kernel_patcher_verification.md
diff --git a/research/kernel_jailbreak_patches/26.5_jb_hook_fixes.md b/Research/KernelJailbreakPatches/26.5_jb_hook_fixes.md
similarity index 100%
rename from research/kernel_jailbreak_patches/26.5_jb_hook_fixes.md
rename to Research/KernelJailbreakPatches/26.5_jb_hook_fixes.md
diff --git a/research/kernel_jailbreak_patches/PATCH_DOC_FRAMEWORK.md b/Research/KernelJailbreakPatches/PATCH_DOC_FRAMEWORK.md
similarity index 100%
rename from research/kernel_jailbreak_patches/PATCH_DOC_FRAMEWORK.md
rename to Research/KernelJailbreakPatches/PATCH_DOC_FRAMEWORK.md
diff --git a/research/kernel_jailbreak_patches/README.md b/Research/KernelJailbreakPatches/README.md
similarity index 92%
rename from research/kernel_jailbreak_patches/README.md
rename to Research/KernelJailbreakPatches/README.md
index 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.md
similarity index 96%
rename from research/kernel_jailbreak_patches/runtime_verification/README.md
rename to Research/KernelJailbreakPatches/RuntimeVerification/README.md
index 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.md
similarity index 100%
rename from research/kernel_jailbreak_patches/runtime_verification/ida_patch_chain_report.md
rename to Research/KernelJailbreakPatches/RuntimeVerification/ida_patch_chain_report.md
diff --git a/research/kernel_jailbreak_patches/runtime_verification/runtime_verification_summary.md b/Research/KernelJailbreakPatches/RuntimeVerification/runtime_verification_summary.md
similarity index 100%
rename from research/kernel_jailbreak_patches/runtime_verification/runtime_verification_summary.md
rename to Research/KernelJailbreakPatches/RuntimeVerification/runtime_verification_summary.md
diff --git a/research/kernel_jailbreak_patches/patch_amfi_cdhash_in_trustcache.md b/Research/KernelJailbreakPatches/patch_amfi_cdhash_in_trustcache.md
similarity index 100%
rename from research/kernel_jailbreak_patches/patch_amfi_cdhash_in_trustcache.md
rename to Research/KernelJailbreakPatches/patch_amfi_cdhash_in_trustcache.md
diff --git a/research/kernel_jailbreak_patches/patch_amfi_execve_kill_path.md b/Research/KernelJailbreakPatches/patch_amfi_execve_kill_path.md
similarity index 100%
rename from research/kernel_jailbreak_patches/patch_amfi_execve_kill_path.md
rename to Research/KernelJailbreakPatches/patch_amfi_execve_kill_path.md
diff --git a/research/kernel_jailbreak_patches/patch_bsd_init_auth.md b/Research/KernelJailbreakPatches/patch_bsd_init_auth.md
similarity index 100%
rename from research/kernel_jailbreak_patches/patch_bsd_init_auth.md
rename to Research/KernelJailbreakPatches/patch_bsd_init_auth.md
diff --git a/research/kernel_jailbreak_patches/patch_convert_port_to_map.md b/Research/KernelJailbreakPatches/patch_convert_port_to_map.md
similarity index 100%
rename from research/kernel_jailbreak_patches/patch_convert_port_to_map.md
rename to Research/KernelJailbreakPatches/patch_convert_port_to_map.md
diff --git a/research/kernel_jailbreak_patches/patch_cred_label_update_execve.md b/Research/KernelJailbreakPatches/patch_cred_label_update_execve.md
similarity index 100%
rename from research/kernel_jailbreak_patches/patch_cred_label_update_execve.md
rename to Research/KernelJailbreakPatches/patch_cred_label_update_execve.md
diff --git a/research/kernel_jailbreak_patches/patch_dounmount.md b/Research/KernelJailbreakPatches/patch_dounmount.md
similarity index 100%
rename from research/kernel_jailbreak_patches/patch_dounmount.md
rename to Research/KernelJailbreakPatches/patch_dounmount.md
diff --git a/research/kernel_jailbreak_patches/patch_hook_cred_label_update_execve.md b/Research/KernelJailbreakPatches/patch_hook_cred_label_update_execve.md
similarity index 100%
rename from research/kernel_jailbreak_patches/patch_hook_cred_label_update_execve.md
rename to Research/KernelJailbreakPatches/patch_hook_cred_label_update_execve.md
diff --git a/research/kernel_jailbreak_patches/patch_io_secure_bsd_root.md b/Research/KernelJailbreakPatches/patch_io_secure_bsd_root.md
similarity index 100%
rename from research/kernel_jailbreak_patches/patch_io_secure_bsd_root.md
rename to Research/KernelJailbreakPatches/patch_io_secure_bsd_root.md
diff --git a/research/kernel_jailbreak_patches/patch_iouc_failed_macf.md b/Research/KernelJailbreakPatches/patch_iouc_failed_macf.md
similarity index 100%
rename from research/kernel_jailbreak_patches/patch_iouc_failed_macf.md
rename to Research/KernelJailbreakPatches/patch_iouc_failed_macf.md
diff --git a/research/kernel_jailbreak_patches/patch_kcall10.md b/Research/KernelJailbreakPatches/patch_kcall10.md
similarity index 100%
rename from research/kernel_jailbreak_patches/patch_kcall10.md
rename to Research/KernelJailbreakPatches/patch_kcall10.md
diff --git a/research/kernel_jailbreak_patches/patch_load_dylinker.md b/Research/KernelJailbreakPatches/patch_load_dylinker.md
similarity index 100%
rename from research/kernel_jailbreak_patches/patch_load_dylinker.md
rename to Research/KernelJailbreakPatches/patch_load_dylinker.md
diff --git a/research/kernel_jailbreak_patches/patch_mac_mount.md b/Research/KernelJailbreakPatches/patch_mac_mount.md
similarity index 100%
rename from research/kernel_jailbreak_patches/patch_mac_mount.md
rename to Research/KernelJailbreakPatches/patch_mac_mount.md
diff --git a/research/kernel_jailbreak_patches/patch_nvram_verify_permission.md b/Research/KernelJailbreakPatches/patch_nvram_verify_permission.md
similarity index 100%
rename from research/kernel_jailbreak_patches/patch_nvram_verify_permission.md
rename to Research/KernelJailbreakPatches/patch_nvram_verify_permission.md
diff --git a/research/kernel_jailbreak_patches/patch_post_validation_additional.md b/Research/KernelJailbreakPatches/patch_post_validation_additional.md
similarity index 100%
rename from research/kernel_jailbreak_patches/patch_post_validation_additional.md
rename to Research/KernelJailbreakPatches/patch_post_validation_additional.md
diff --git a/research/kernel_jailbreak_patches/patch_proc_pidinfo.md b/Research/KernelJailbreakPatches/patch_proc_pidinfo.md
similarity index 100%
rename from research/kernel_jailbreak_patches/patch_proc_pidinfo.md
rename to Research/KernelJailbreakPatches/patch_proc_pidinfo.md
diff --git a/research/kernel_jailbreak_patches/patch_proc_security_policy.md b/Research/KernelJailbreakPatches/patch_proc_security_policy.md
similarity index 100%
rename from research/kernel_jailbreak_patches/patch_proc_security_policy.md
rename to Research/KernelJailbreakPatches/patch_proc_security_policy.md
diff --git a/research/kernel_jailbreak_patches/patch_sandbox_hooks_extended.md b/Research/KernelJailbreakPatches/patch_sandbox_hooks_extended.md
similarity index 100%
rename from research/kernel_jailbreak_patches/patch_sandbox_hooks_extended.md
rename to Research/KernelJailbreakPatches/patch_sandbox_hooks_extended.md
diff --git a/research/kernel_jailbreak_patches/patch_shared_region_map.md b/Research/KernelJailbreakPatches/patch_shared_region_map.md
similarity index 100%
rename from research/kernel_jailbreak_patches/patch_shared_region_map.md
rename to Research/KernelJailbreakPatches/patch_shared_region_map.md
diff --git a/research/kernel_jailbreak_patches/patch_spawn_validate_persona.md b/Research/KernelJailbreakPatches/patch_spawn_validate_persona.md
similarity index 100%
rename from research/kernel_jailbreak_patches/patch_spawn_validate_persona.md
rename to Research/KernelJailbreakPatches/patch_spawn_validate_persona.md
diff --git a/research/kernel_jailbreak_patches/patch_syscallmask_apply_to_proc.md b/Research/KernelJailbreakPatches/patch_syscallmask_apply_to_proc.md
similarity index 100%
rename from research/kernel_jailbreak_patches/patch_syscallmask_apply_to_proc.md
rename to Research/KernelJailbreakPatches/patch_syscallmask_apply_to_proc.md
diff --git a/research/kernel_jailbreak_patches/patch_task_conversion_eval_internal.md b/Research/KernelJailbreakPatches/patch_task_conversion_eval_internal.md
similarity index 100%
rename from research/kernel_jailbreak_patches/patch_task_conversion_eval_internal.md
rename to Research/KernelJailbreakPatches/patch_task_conversion_eval_internal.md
diff --git a/research/kernel_jailbreak_patches/patch_task_for_pid.md b/Research/KernelJailbreakPatches/patch_task_for_pid.md
similarity index 100%
rename from research/kernel_jailbreak_patches/patch_task_for_pid.md
rename to Research/KernelJailbreakPatches/patch_task_for_pid.md
diff --git a/research/kernel_jailbreak_patches/patch_thid_should_crash.md b/Research/KernelJailbreakPatches/patch_thid_should_crash.md
similarity index 100%
rename from research/kernel_jailbreak_patches/patch_thid_should_crash.md
rename to Research/KernelJailbreakPatches/patch_thid_should_crash.md
diff --git a/research/kernel_jailbreak_patches/patch_thread_set_state.md b/Research/KernelJailbreakPatches/patch_thread_set_state.md
similarity index 100%
rename from research/kernel_jailbreak_patches/patch_thread_set_state.md
rename to Research/KernelJailbreakPatches/patch_thread_set_state.md
diff --git a/research/kernel_jailbreak_patches/patch_vm_fault_enter_prepare.md b/Research/KernelJailbreakPatches/patch_vm_fault_enter_prepare.md
similarity index 100%
rename from research/kernel_jailbreak_patches/patch_vm_fault_enter_prepare.md
rename to Research/KernelJailbreakPatches/patch_vm_fault_enter_prepare.md
diff --git a/research/kernel_jailbreak_patches/patch_vm_map_delete_immutable_code.md b/Research/KernelJailbreakPatches/patch_vm_map_delete_immutable_code.md
similarity index 100%
rename from research/kernel_jailbreak_patches/patch_vm_map_delete_immutable_code.md
rename to Research/KernelJailbreakPatches/patch_vm_map_delete_immutable_code.md
diff --git a/research/kernel_jailbreak_patches/patch_vm_map_protect.md b/Research/KernelJailbreakPatches/patch_vm_map_protect.md
similarity index 100%
rename from research/kernel_jailbreak_patches/patch_vm_map_protect.md
rename to Research/KernelJailbreakPatches/patch_vm_map_protect.md
diff --git a/research/kernel_symbols/kernel_index.tsv b/Research/KernelSymbols/kernel_index.tsv
similarity index 100%
rename from research/kernel_symbols/kernel_index.tsv
rename to Research/KernelSymbols/kernel_index.tsv
diff --git a/research/kernel_symbols/kernel_symbols.db b/Research/KernelSymbols/kernel_symbols.db
similarity index 100%
rename from research/kernel_symbols/kernel_symbols.db
rename to Research/KernelSymbols/kernel_symbols.db
diff --git a/research/kernel_symbols/summary.tsv b/Research/KernelSymbols/summary.tsv
similarity index 100%
rename from research/kernel_symbols/summary.tsv
rename to Research/KernelSymbols/summary.tsv
diff --git a/research/patches/cfw_patch_launchd_jetsam.md b/Research/Patches/cfw_patch_launchd_jetsam.md
similarity index 100%
rename from research/patches/cfw_patch_launchd_jetsam.md
rename to Research/Patches/cfw_patch_launchd_jetsam.md
diff --git a/research/patches/hv_vmm_present_usermode_xrefs.md b/Research/Patches/hv_vmm_present_usermode_xrefs.md
similarity index 100%
rename from research/patches/hv_vmm_present_usermode_xrefs.md
rename to Research/Patches/hv_vmm_present_usermode_xrefs.md
diff --git a/research/patches/patch_reference_capture.md b/Research/Patches/patch_reference_capture.md
similarity index 100%
rename from research/patches/patch_reference_capture.md
rename to Research/Patches/patch_reference_capture.md
diff --git a/Research/README.md b/Research/README.md
new file mode 100644
index 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.md
similarity index 100%
rename from research/restore/p2_dfu_spike.md
rename to Research/Restore/p2_dfu_spike.md
diff --git a/research/restore/p2_restore_off_python.md b/Research/Restore/p2_restore_off_python.md
similarity index 100%
rename from research/restore/p2_restore_off_python.md
rename to Research/Restore/p2_restore_off_python.md
diff --git a/research/VPhoneVirtualMachineRefactored.swift b/Research/VPhoneVirtualMachineRefactored.swift
similarity index 100%
rename from research/VPhoneVirtualMachineRefactored.swift
rename to Research/VPhoneVirtualMachineRefactored.swift
diff --git a/research/hv_vmm_present_xref.json b/Research/hv_vmm_present_xref.json
similarity index 100%
rename from research/hv_vmm_present_xref.json
rename to Research/hv_vmm_present_xref.json
diff --git a/research/vphoned_http_api.md b/Research/vphoned_http_api.md
similarity index 100%
rename from research/vphoned_http_api.md
rename to Research/vphoned_http_api.md
diff --git a/Scripts/build.sh b/Scripts/build.sh
index 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.z
rm -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.md
similarity index 69%
rename from skills/kernel-analysis-vphone600/SKILL.md
rename to Skills/kernel-analysis-vphone600/SKILL.md
index 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 Rules
diff --git a/skills/kernel-analysis-vphone600/agents/openai.yaml b/Skills/kernel-analysis-vphone600/agents/openai.yaml
similarity index 100%
rename from skills/kernel-analysis-vphone600/agents/openai.yaml
rename to Skills/kernel-analysis-vphone600/agents/openai.yaml
diff --git a/Skills/kernel-analysis-vphone600/references/kernel-info-queries.md b/Skills/kernel-analysis-vphone600/references/kernel-info-queries.md
new file mode 100644
index 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.swift
index 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 dumps
diff --git a/Sources/FirmwarePatcher/CustomFirmware/ExecutablePatches/CustomFirmwareCacheLoader.swift b/Sources/FirmwarePatcher/CustomFirmware/ExecutablePatches/CustomFirmwareCacheLoader.swift
index 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.swift
index 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 return
diff --git a/Sources/FirmwarePatcher/DyldSharedCache/Patchers/DyldSharedCacheHypervisorVirtualMachinePatcher.swift b/Sources/FirmwarePatcher/DyldSharedCache/Patchers/DyldSharedCacheHypervisorVirtualMachinePatcher.swift
index 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.swift
index 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, and
diff --git a/Sources/FirmwarePatcher/DyldSharedCache/Patchers/DyldSharedCacheXPCLWCRPatcher.swift b/Sources/FirmwarePatcher/DyldSharedCache/Patchers/DyldSharedCacheXPCLWCRPatcher.swift
index 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.swift
index 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 Capstone
import Foundation
diff --git a/Sources/FirmwarePatcher/Kernel/JailbreakPatches/Frida/KernelJailbreakPatchVmMapDelete.swift b/Sources/FirmwarePatcher/Kernel/JailbreakPatches/Frida/KernelJailbreakPatchVmMapDelete.swift
index 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 Capstone
import Foundation
diff --git a/Sources/VPhoneArchive/VPhoneArchiveWriter.swift b/Sources/VPhoneArchive/VPhoneArchiveWriter.swift
index 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.swift
index 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.path
let needsCatalog = list || iphoneVersion != nil || iphoneBuild != nil
let urls = if needsCatalog {
try vphoneRunBlocking {
diff --git a/Sources/VPhoneCore/VPhoneGuestLauncher.swift b/Sources/VPhoneCore/VPhoneGuestLauncher.swift
index 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.md
for host settings.
"""
diff --git a/Tests/VPhoneArchiveTests/BundleTransferTests.swift b/Tests/VPhoneArchiveTests/BundleTransferTests.swift
index 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.swift
index 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.md
deleted file mode 100644
index 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.md
deleted file mode 100644
index 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.