docs(pi): document vendored update workflow

git-subtree-dir: third_party/pi
git-subtree-split: d981de1229ef899957bbe968bc8dcda02a21f477

AGENTS.md

@@ -110,7 +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` as a linear vendor import.
-  Do not use `git subtree add` or `git subtree pull` for Pi PR branches.
-  Gitea rebases the synthetic upstream root commit without the `third_party/pi` prefix.
-  Preserve `git-subtree-dir` and `git-subtree-split` trailers on Pi vendor commits.
+- 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.

README.md

@@ -13,8 +13,7 @@ dev/                    Monorepo root
 ├── src/                 Projects
 │   └── dotfiles/        Home and system configuration
 └── third_party/         External source and vendoring support
-    ├── crates/          Generated Rust crate sources and Bazel targets
-    └── pi/              Vendored Pi source
+    └── crates/          Generated Rust crate sources and Bazel targets
 ```
 
 ## Rust dependencies
@@ -48,36 +47,23 @@ Do not edit generated files manually.
 ## Vendored Pi
 
 Pi source lives in `third_party/pi/`.
-The directory is a linear vendor import from upstream Pi.
+This directory is a squashed `git subtree` import from upstream Pi.
 Local fork changes are carried directly in that vendored tree.
 
-Use the upstream tag that matches the target CLI release.
-The CLI version lives in `packages/coding-agent/package.json`.
-
-Do not use `git subtree add` or `git subtree pull` for Pi PR branches.
-Those commands create a synthetic upstream root commit.
-Gitea rebase applies that root commit without the `third_party/pi` prefix.
-That causes add/add conflicts on repository root files.
-
-Update the vendor tree with a linear commit:
+Update Pi with `git subtree pull`.
+Use the upstream tag that matches the target CLI release:
 
 ```sh
-git fetch https://github.com/earendil-works/pi.git refs/tags/v<version>
-split="$(git rev-parse FETCH_HEAD)"
-rm -rf third_party/pi
-mkdir -p third_party/pi
-git archive --format=tar "$split" | tar -C third_party/pi -xf -
-git add third_party/pi
-git commit \
-  -m "chore(vendor): import pi <version>" \
-  -m "Imported as a linear vendor commit so forge rebases do not replay the upstream root tree." \
-  -m "git-subtree-dir: third_party/pi" \
-  -m "git-subtree-split: $split"
+git subtree pull \
+  --prefix=third_party/pi \
+  https://github.com/earendil-works/pi.git \
+  v<version> \
+  --squash
 ```
 
-Keep the vendor import or update commit separate from local edits.
-Do not remove the `git-subtree-dir` and `git-subtree-split` trailers.
-They record the upstream source commit for future updates.
+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.