docs(pi): document linear vendor workflow

Imported as a linear vendor commit so forge rebases do not replay the upstream root tree.

git-subtree-dir: third_party/pi

git-subtree-split: d981de1229ef899957bbe968bc8dcda02a21f477

AGENTS.md

@@ -110,6 +110,7 @@
   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.
+- 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.

README.md

@@ -13,7 +13,8 @@ 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
+    ├── crates/          Generated Rust crate sources and Bazel targets
+    └── pi/              Vendored Pi source
 ```
 
 ## Rust dependencies
@@ -47,23 +48,36 @@ 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.
+The directory is a linear vendor 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:
+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:
 
 ```sh
-git subtree pull \
-  --prefix=third_party/pi \
-  https://github.com/earendil-works/pi.git \
-  v<version> \
-  --squash
+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"
 ```
 
-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.
+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.
 
 After the upstream update, resolve conflicts in `third_party/pi/`.
 Keep local fork changes as ordinary commits after the vendor update.