From b6613b3a04e0498adc2ceeccb07bdc87b2d800e9 Mon Sep 17 00:00:00 2001
From: alexion <contact@alexion.dev>
Date: Mon, 14 Sep 2026 10:49:19 -0400
Subject: [PATCH] docs(pi): document linear vendor workflow

---
 AGENTS.md |  4 ++++
 README.md | 45 ++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 48 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index a9958f5..993638c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -110,3 +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` 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.
diff --git a/README.md b/README.md
index 9991994..94b2eeb 100644
--- a/README.md
+++ b/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
@@ -44,3 +45,45 @@ 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/`.
+The directory is a linear vendor 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:
+
+```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"
+```
+
+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.
+Then verify the package:
+
+```sh
+nix build .#nixosConfigurations.zeus.config.home-manager.users.alexion.programs.pi-coding-agent.package --no-link --print-out-paths
+```
+