diff --git a/AGENTS.md b/AGENTS.md
index a9958f5..af733a5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -110,3 +110,6 @@
   absent from the pinned revision or from a different branch such as `nixpkgs-unstable`.
 - OMP does not discover project skills from `.pi/skills`.
   Put skills shared by Pi and OMP under `.agents/skills`, or configure OMP's `skills.customDirectories`.
+- Pi is vendored under `third_party/pi` with `git subtree --squash`.
+  Keep subtree import and update commits separate from local edits.
+  Do not remove `git-subtree-dir` or `git-subtree-split` trailers when rewriting Pi history.
diff --git a/README.md b/README.md
index 9991994..5bb41da 100644
--- a/README.md
+++ b/README.md
@@ -44,3 +44,32 @@ deps = ["//third_party/crates:crate_name"]
 Commit the generated files under `third_party/crates/`.
 Do not edit generated files manually.
 
+## Vendored Pi
+
+Pi source lives in `third_party/pi/`.
+This directory is a squashed `git subtree` import from upstream Pi.
+Local fork changes are carried directly in that vendored tree.
+
+Update Pi with `git subtree pull`.
+Use the upstream tag that matches the target CLI release:
+
+```sh
+git subtree pull \
+  --prefix=third_party/pi \
+  https://github.com/earendil-works/pi.git \
+  v<version> \
+  --squash
+```
+
+Keep the subtree import or update commit separate from local edits.
+Do not squash away the `git-subtree-dir` and `git-subtree-split` trailers.
+Future subtree updates use those trailers to find prior imports.
+
+After the upstream update, resolve conflicts in `third_party/pi/`.
+Keep local fork changes as ordinary commits after the vendor update.
+Then verify the package:
+
+```sh
+nix build .#nixosConfigurations.zeus.config.home-manager.users.alexion.programs.pi-coding-agent.package --no-link --print-out-paths
+```
+