From 8bee09c815a5ee8ecbc4188bcdb43e4a5610e00e Mon Sep 17 00:00:00 2001
From: NotoriousRebel <36310667+NotoriousRebel@users.noreply.github.com>
Date: Sat, 15 Aug 2026 22:28:22 -0400
Subject: [PATCH] docs: distinguish GitHub connectivity from auth failures

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

diff --git a/AGENTS.md b/AGENTS.md
index d1ce9aba..2f55a3de 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -30,17 +30,18 @@ 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.
 - Run the full non-browser suite once at the publication head. Dependent stack layers do not need to repeat it unless they change Python behavior.
 - Run the HarvestView browser suite once at the final UI head or rely on its GitHub workflow. Static UI edits should use focused UI tests and a JavaScript syntax check first.
 - Before retrying a long-running test, confirm the previous process exited. Poll the existing command or stop only its exact owned process instead of starting an overlapping run.
+
+## GitHub CLI diagnostics
+
+Before reporting broken GitHub authentication, distinguish connectivity from
+credential failure. Run `gh api user --silent` in the same host execution
+context used for `git push`, then inspect any error. A sandboxed `gh auth
+status` failure alone is not credential evidence. Report DNS, network, and
+GitHub service failures as connectivity blockers. Use browser publication only
+when the host-side command specifically reports missing or invalid credentials.