docs(agent): clarify cred-file set + settings doc pointer, fix forge_notify cross-ref

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
+    // Forgejo's notification `subject.type` is "Pull" / "Issue", never
-    // "Pull Request") — see the comment in `build_meta_suffix` below.
+    // "Pull Request".
     let is_pr = notif_type == "Pull";
     let meta_suffix = build_meta_suffix(subject.as_ref(), is_pr);
 

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`]?

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`
+// 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`
+// which claude-code auto-discovers (precedence #1, read-only, un-overridable) —
-// asset). claude-code auto-discovers that managed path — precedence #1,
+// so the harness no longer passes `--settings`. We turn off claude's in-session
-// read-only, un-overridable — so the harness no longer passes `--settings`.
+// auto-compaction and its cross-session auto-memory because hyperhive owns those
-// We turn off claude's in-session auto-compaction and its cross-session
+// concerns (`/compact` on overflow, notes persistence under `/state`). How the
-// auto-memory because hyperhive owns those concerns (`/compact` on overflow,
+// file is wired (the nix asset) + the full rationale live in
-// notes persistence under `/state`). Unknown keys are silently ignored by
+// `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
+// claude-code; if a key gets renamed we'll spot it because the corresponding
-// corresponding behavior will start firing mid-turn again.
+// behavior will start firing mid-turn again.
 //
 // The subprocess mechanics — spawning `claude --print`, streaming +
 // classifying stream-json, session lookup/archive — live in the generic