diff --git a/AGENTS.md b/AGENTS.md
index c32cb8c64b..ffe6f364e9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -2,8 +2,49 @@
 
 This file provides guidance to agents when working with code in this repository.
 
-- Settings View Pattern: When working on `SettingsView`, inputs must bind to the local `cachedState`, NOT the live `useExtensionState()`. The `cachedState` acts as a buffer for user edits, isolating them from the `ContextProxy` source-of-truth until the user explicitly clicks "Save". Wiring inputs directly to the live state causes race conditions.
-- Changesets: Do NOT create `.changeset` files for each commit or code change. Changesets are managed separately by maintainers and should not be generated by agents during normal development.
+---
+
+## Project Systems Overview
+
+Before making ANY changes, be aware of these already-implemented systems:
+
+### 1. Governance System
+
+- **`WORKSPACE_GOVERNANCE.md`** — Absolute rules: no shortcuts, no cheating, plan first, no half-work, industry standard quality.
+- **`PLANNING_REQUIRED.md`** — 5-stage pipeline: Research -> Design -> Plan -> Review -> Execute. Zero code without a plan.
+- **`docs/ARCHITECTURE.md`** — Full architecture reference.
+- **`docs/REQUIREMENTS.md`** — Standing requirements.
+- **`docs/DEV_SETUP.md`** — Dev environment setup.
+- **BRANCH STRATEGY**: Feature branches + PR only. NEVER push directly to `main`.
+
+### 2. Upstream Sync System (Zoo-Code-Org/Zoo-Code)
+
+This fork tracks upstream with **selective cherry-pick** (NOT merge):
+
+- **`.upstream/STATE.json`** — Tracks last fetched SHA, imported/skipped/pending commit lists. Committed to repo (lives on GitHub).
+- **`.upstream/COMMITS.md`** — Human-readable log of import/skip decisions.
+- **`scripts/upstream-check.ps1`** — Fetch upstream, list new commits, update STATE.json.
+- **`scripts/upstream-import.ps1 <sha>`** — Cherry-pick specific commit, mark as IMPORTED.
+- **`scripts/upstream-skip.ps1 <sha> "<reason>"`** — Mark commit as SKIPPED with reason.
+- **Workflow**: `pnpm upstream:check` -> review -> `pnpm upstream:import <sha>` or `pnpm upstream:skip <sha> "<reason>"`
+- **Docs**: `docs/upstream-sync/README.md`, ADR-004 in `docs/decisions/`.
+- **NEVER** `git merge upstream/main` — only selective cherry-pick.
+
+### 3. ADR Decision Log
+
+All architecture decisions documented in `docs/decisions/`:
+
+- ADR-001: Workspace Governance
+- ADR-002: Branch Strategy & PR Workflow
+- ADR-003: Tool Selection & Development Stack
+- ADR-004: Selective Upstream Sync System
+
+---
+
+## Code Guidance
+
+- **Settings View Pattern**: When working on `SettingsView`, inputs must bind to the local `cachedState`, NOT the live `useExtensionState()`. The `cachedState` acts as a buffer for user edits, isolating them from the `ContextProxy` source-of-truth until the user explicitly clicks "Save". Wiring inputs directly to the live state causes race conditions.
+- **Changesets**: Do NOT create `.changeset` files for each commit or code change. Changesets are managed separately by maintainers and should not be generated by agents during normal development.
 
 ## Test Placement Guidance