From 8a78b8a46423af69c42b6a9a64368d20ab7c1610 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?m=C3=BCde?= <git@darkest.space>
Date: Mon, 6 Jul 2026 00:03:43 +0200
Subject: [PATCH] docs(agent): clarify cred-file set + settings doc pointer,
 fix forge_notify cross-ref

---
 hive-ag3nt/src/forge_notify.rs |  4 ++--
 hive-ag3nt/src/login.rs        |  7 +++++++
 hive-ag3nt/src/turn.rs         | 18 +++++++++---------
 3 files changed, 18 insertions(+), 11 deletions(-)

diff --git a/hive-ag3nt/src/forge_notify.rs b/hive-ag3nt/src/forge_notify.rs
index 99a1f225..21af21e1 100644
--- a/hive-ag3nt/src/forge_notify.rs
+++ b/hive-ag3nt/src/forge_notify.rs
@@ -392,8 +392,8 @@ async fn format_notification(
         fetch_json(client, subject_api_url, token).await
     };
 
-    // Forgejo's notification `subject.type` is "Pull" / "Issue" (never
-    // "Pull Request") — see the comment in `build_meta_suffix` below.
+    // Forgejo's notification `subject.type` is "Pull" / "Issue", never
+    // "Pull Request".
     let is_pr = notif_type == "Pull";
     let meta_suffix = build_meta_suffix(subject.as_ref(), is_pr);
 
diff --git a/hive-ag3nt/src/login.rs b/hive-ag3nt/src/login.rs
index 18468e85..f5302e77 100644
--- a/hive-ag3nt/src/login.rs
+++ b/hive-ag3nt/src/login.rs
@@ -33,6 +33,13 @@ pub fn default_dir() -> PathBuf {
 /// Rationale + the previous wholesale-wipe shape we replaced live in
 /// [`docs/web-ui/agent.md::Per-agent endpoints`](../../docs/web-ui/agent.md)
 /// (the `/api/logout` bullet).
+///
+/// `.credentials.json` is the actual OAuth session; `mcp-needs-auth-cache.json`
+/// is claude-code's MCP-auth cache and a weaker signal. Both are kept in the
+/// set only because `/logout` deletes both, so the "either present ⇒ logged
+/// in" check can never disagree with a logout. (If a future edit ever removes
+/// `.credentials.json` without the cache — a state `/logout` doesn't produce —
+/// keying purely on `.credentials.json` would be the stronger boot signal.)
 pub const CRED_FILE_NAMES: &[&str] = &[".credentials.json", "mcp-needs-auth-cache.json"];
 
 /// Is `entry` a regular file whose name is one of [`CRED_FILE_NAMES`]?
diff --git a/hive-ag3nt/src/turn.rs b/hive-ag3nt/src/turn.rs
index bbaf5708..3d5d9582 100644
--- a/hive-ag3nt/src/turn.rs
+++ b/hive-ag3nt/src/turn.rs
@@ -14,15 +14,15 @@ use serde_json::Value;
 use crate::events::{Bus, LiveEvent};
 use crate::mcp_config;
 
-// Hive-enforced claude settings ship at `/etc/claude-code/managed-settings.json`
-// (wired in `nix/templates/harness-base.nix` from the `prompts/claude-settings.json`
-// asset). claude-code auto-discovers that managed path — precedence #1,
-// read-only, un-overridable — so the harness no longer passes `--settings`.
-// We turn off claude's in-session auto-compaction and its cross-session
-// auto-memory because hyperhive owns those concerns (`/compact` on overflow,
-// notes persistence under `/state`). Unknown keys are silently ignored by
-// claude-code; if a key gets renamed we'll spot it because the
-// corresponding behavior will start firing mid-turn again.
+// Hive-enforced claude settings ship at `/etc/claude-code/managed-settings.json`,
+// which claude-code auto-discovers (precedence #1, read-only, un-overridable) —
+// so the harness no longer passes `--settings`. We turn off claude's in-session
+// auto-compaction and its cross-session auto-memory because hyperhive owns those
+// concerns (`/compact` on overflow, notes persistence under `/state`). How the
+// file is wired (the nix asset) + the full rationale live in
+// `docs/turn-loop/claude-invocation.md`. Unknown keys are silently ignored by
+// claude-code; if a key gets renamed we'll spot it because the corresponding
+// behavior will start firing mid-turn again.
 //
 // The subprocess mechanics — spawning `claude --print`, streaming +
 // classifying stream-json, session lookup/archive — live in the generic