diff --git a/AGENTS.md b/AGENTS.md
index 8ad0cddb..84ea03ff 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -3,3 +3,47 @@
 This project keeps a single source of truth for agent/contributor conventions in [`CLAUDE.md`](./CLAUDE.md). **Read [`CLAUDE.md`](./CLAUDE.md) and follow it.**
 
 @CLAUDE.md
+
+## Downstream fork workflow
+
+This repo is a **downstream fork** that customizes the product appearance on top of
+upstream `gpustack/gpustack-ui`. The mirror chain is:
+
+```
+upstream  https://github.com/gpustack/gpustack-ui.git
+   |  (fetch)
+origin    ssh://git@192.168.0.23:11022/root/gpustack-ui.git   (private registry, also https://git.digiman.live)
+```
+
+### Goal
+
+Track upstream releases. When upstream changes, we pull it in, then apply our own
+appearance/customization changes on a dedicated branch so we keep our look-and-feel
+on top of the latest upstream product.
+
+### Branch naming
+
+Customization work lives on `v<upstream-version>-lofyer` branches (e.g.
+`v2.2.0-lofyer`). Each time upstream ships a new version we want to follow, create a
+new `v<version>-lofyer` branch from the corresponding upstream tag/branch and re-apply
+(or rebase) our customizations onto it.
+
+### Syncing from upstream
+
+`scripts/sync-github` mirrors upstream into the private `origin` (full mirror, force
+push of all branches + tags). It auto-configures the `upstream` remote on first run.
+
+```bash
+# preview only, no push
+DRY_RUN=1 ./scripts/sync-github
+
+# real sync (force-pushes every upstream branch + tag to origin)
+./scripts/sync-github
+
+# also delete origin branches that no longer exist upstream (true mirror, destructive)
+PRUNE_BRANCHES=1 ./scripts/sync-github
+```
+
+Env knobs: `UPSTREAM_URL`, `ORIGIN_REMOTE`, `UPSTREAM_REMOTE`, `PRUNE_BRANCHES`,
+`DRY_RUN`. After syncing, branch a fresh `v<version>-lofyer` off the updated upstream
+ref and apply the appearance changes there.