From 3e9058a44b2e76f6e69e44d9feccd59f75f26fad Mon Sep 17 00:00:00 2001
From: NotoriousRebel <36310667+NotoriousRebel@users.noreply.github.com>
Date: Sat, 15 Aug 2026 21:34:16 -0400
Subject: [PATCH] docs: clarify GitHub CLI auth diagnostics

---
 AGENTS.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index a688dc75..d1ce9aba 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -30,6 +30,14 @@ Read [CONTEXT.md](CONTEXT.md) when changing discovery terminology, evidence clas
 
 Run focused checks first and expand according to risk. Report any skipped check and its reason.
 
+## GitHub CLI diagnostics
+
+Before reporting broken GitHub authentication, distinguish sandbox or network
+isolation from credential failure. Run `gh api user --jq .login` in the same
+host execution context used for `git push`; a sandboxed `gh auth status`
+failure alone is not credential evidence. Prefer authenticated `gh` or API
+publication, and use browser publication only after the host-side check fails.
+
 ### Test budget
 
 - During implementation, run the narrowest test that covers the changed behavior. Do not rerun the full suite after every small edit.