From 8a92c0dc93ac1bcda993ec653351d2c0ada674d3 Mon Sep 17 00:00:00 2001
From: root <root@localhost.localdomain>
Date: Mon, 23 Feb 2026 16:47:56 +0800
Subject: [PATCH] docs: add upstream and periodic sync guide

---
 AGENTS.md | 20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index 5c6d092be..a121923ba 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -3,6 +3,25 @@
 ## Scope
 This file applies to the `picoclaw` project root.
 
+## Git Upstream and Periodic Sync
+
+Current remote setup:
+- `origin`: `https://github.com/xwysyy/picoclaw.git` (your fork)
+- `upstream`: `https://github.com/sipeed/picoclaw.git` (original project)
+
+If `upstream` is missing, add it:
+- `git remote add upstream https://github.com/sipeed/picoclaw.git`
+
+### Periodic sync routine (recommended)
+Run these commands regularly to sync latest upstream changes into your fork branch:
+1. `source ~/.zshrc && proxy_on && git fetch upstream`
+2. `git checkout main`
+3. `git rebase upstream/main`
+4. `source ~/.zshrc && proxy_on && git push origin main`
+
+If your workflow prefers merge over rebase, use:
+- `git merge upstream/main`
+
 ## Known API Error: `No tool output found for function call`
 
 ### Symptom
@@ -58,4 +77,3 @@ Expected healthy state:
 In non-interactive command contexts, use:
 
 - `source ~/.zshrc && proxy_on && <your-command>`
-