From eac574dc8f25c063bbe18bac84cefef59ad895b7 Mon Sep 17 00:00:00 2001
From: garrytan <garrytan@gmail.com>
Date: Sun, 1 Nov 2026 14:40:06 +0000
Subject: [PATCH] docs(gbrain-detect): say what gbrain_doctor_ok proves under
 --fast

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
---
 bin/gstack-gbrain-detect | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/bin/gstack-gbrain-detect b/bin/gstack-gbrain-detect
index 8e69eaba1..8183cd768 100755
--- a/bin/gstack-gbrain-detect
+++ b/bin/gstack-gbrain-detect
@@ -178,9 +178,10 @@ function runDoctor(extraArgs: string[], timeoutMs: number): DoctorVerdict {
   };
 }
 
-// Uses --fast to avoid hanging on a dead DB. Per the local-status classifier
-// (which probes DB directly via `gbrain sources list`), gbrain_doctor_ok is a
-// coarse health summary, not engine-reachability — that's gbrain_local_status.
+// Uses --fast to avoid hanging on a dead DB. --fast skips every DB check, so
+// gbrain_doctor_ok only says doctor ran and its filesystem checks passed; it
+// proves nothing about the brain's data. Step 5 runs the full --doctor gate.
+// Engine reachability is gbrain_local_status (it probes `gbrain sources list`).
 function detectDoctor(onPath: boolean): boolean {
   if (!onPath) return false;
   return runDoctor(["--fast"], 3_000).brain_ok;