From bc6b2dd84c67b73f480e60e0770cffe0503470a3 Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Tue, 20 Oct 2026 15:21:57 -0700
Subject: [PATCH] docs: load Git guidance on demand [skip ci]

---
 .gitignore                     |  2 ++
 AGENTS.md                      | 22 ++--------------------
 docs/reference/git-workflow.md | 23 +++++++++++++++++++++++
 3 files changed, 27 insertions(+), 20 deletions(-)
 create mode 100644 docs/reference/git-workflow.md

diff --git a/.gitignore b/.gitignore
index 0839c1cf0f9..ae1f30644b3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -117,6 +117,8 @@ docs/**
 !docs/bug-reproductions/
 !docs/bug-reproductions/**
 !docs/STYLEGUIDE.md
+!docs/reference/
+!docs/reference/git-workflow.md
 !docs/audits/
 !docs/audits/crashpad-read-limit/
 !docs/audits/crashpad-read-limit/source-hashes.json
diff --git a/AGENTS.md b/AGENTS.md
index fa73d9afb1c..8ad2bd1c5e3 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -41,10 +41,6 @@ Avoid type assertions except `as const`. Unavoidable casts need a line-specific
 - **Lint**: `oxlint`, or `pnpm run check:code-quality:changed` for changed files (full `pnpm lint` is slow); format with `pnpm format`
 - **Design system**: `pnpm run lint:design-system` for the full renderer report (not a gate); the changed-lines gate above is what CI enforces
 
-## Merging Pull Requests
-
-Before merging, verify that the required checks and aggregate gate in the full PR workflow have pass.
-
 # Considerations
 
 ## Worktree Safety
@@ -86,20 +82,6 @@ The execution host owns agent status in one store, the hook server's, and every
 
 Clients and remote Orca servers update independently, so mixed versions are the normal state.
 
-## Git Binary Compatibility
+## Git and Review Work
 
-Orca runs the user's Git binary on native, WSL, and SSH hosts, which may all have different versions. Treat Git 2.25 as the core-workflow baseline.
-
-## Git Scan Safety
-
-- Never enumerate every ref and then run `git ls-tree -r` or `git show` once per ref. That ref × tree fan-out can retain gigabytes of output before a downstream `sort -u` or search can make progress.
-- Prefer `rg` over the checked-out files for source searches. For history or refs, use a named ref, an explicit namespace/path, `--max-count`, and a bounded output; do not use an unqualified `--all` scan as a first diagnostic.
-- Keep repository-wide commands targeted to the current repository and worktree. If an unbounded scan is genuinely required, measure the ref count first, explain the cost, and get confirmation before running it.
-
-## Git Provider Compatibility
-
-Source-control and review changes must consider GitLab and other supported git providers, not only GitHub. Keep provider-specific behavior behind explicit checks, and avoid GitHub-only naming for generic review concepts.
-
-## GitHub CLI Usage
-
-Be mindful of the user's `gh` CLI API rate limit — batch requests where possible and avoid unnecessary calls. All code, commands, and scripts must be compatible with macOS, Linux, and Windows.
+Before running Git or `gh` commands, changing source-control or review behavior, or merging a pull request, read [`docs/reference/git-workflow.md`](./docs/reference/git-workflow.md).
diff --git a/docs/reference/git-workflow.md b/docs/reference/git-workflow.md
new file mode 100644
index 00000000000..330d845eead
--- /dev/null
+++ b/docs/reference/git-workflow.md
@@ -0,0 +1,23 @@
+# Git and Review Work
+
+## Git Binary Compatibility
+
+Orca runs the user's Git binary on native, WSL, and SSH hosts, which may all have different versions. Treat Git 2.25 as the core-workflow baseline.
+
+## Git Scan Safety
+
+- Never enumerate every ref and then run `git ls-tree -r` or `git show` once per ref. That ref × tree fan-out can retain gigabytes of output before a downstream `sort -u` or search can make progress.
+- Prefer `rg` over the checked-out files for source searches. For history or refs, use a named ref, an explicit namespace/path, `--max-count`, and a bounded output; do not use an unqualified `--all` scan as a first diagnostic.
+- Keep repository-wide commands targeted to the current repository and worktree. If an unbounded scan is genuinely required, measure the ref count first, explain the cost, and get confirmation before running it.
+
+## Git Provider Compatibility
+
+Source-control and review changes must consider GitLab and other supported git providers, not only GitHub. Keep provider-specific behavior behind explicit checks, and avoid GitHub-only naming for generic review concepts.
+
+## GitHub CLI Usage
+
+Be mindful of the user's `gh` CLI API rate limit — batch requests where possible and avoid unnecessary calls. All code, commands, and scripts must be compatible with macOS, Linux, and Windows.
+
+## Merging Pull Requests
+
+Before merging, verify that the required checks and aggregate gate in the full PR workflow have pass.