From 052767c25b662383a733dfbc9905eabe2ffe4ea5 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sun, 2 Aug 2026 23:54:55 +0200
Subject: [PATCH] docs(github): move impl detail below the operator-facing
 sections

github.md mixed operator content (enabling, provisioning, security)
with deep implementation detail (the gh wrapper/credential-helper
mechanics, the notification poller's internals) in file order, so an
operator reading top-to-bottom hits internals before finishing the
part they actually need.

Pure reorder, no rewrite: Enabling -> Provisioning -> Security (all
operator-facing) now come first: How the agent uses it and
Notifications (both pure impl detail) move to the end, with a one-line
marker between them. Every word of existing content is unchanged, only
section order moved - lowest-risk shape for a file like this with no
subdirectory to split into (see hyperhive#1898).
---
 docs/github.md | 55 ++++++++++++++++++++++++++------------------------
 1 file changed, 29 insertions(+), 26 deletions(-)

diff --git a/docs/github.md b/docs/github.md
index 8e69915f..9dfecf4a 100644
--- a/docs/github.md
+++ b/docs/github.md
@@ -31,6 +31,35 @@ hive-wide host switch is the intended control.)
 github.com only. The token **value** never touches nix — it is written to
 `<state>/github-token` separately (see [Provisioning](#provisioning)).
 
+## Provisioning
+
+The PAT is operator-supplied. The primary path is the **dashboard
+credentials tab** (github sub-tab): paste the PAT for an agent and submit
+(`POST /api/github-account`). There is also a CLI path for
+recovery/scripting:
+
+```sh
+hivectl github set-token <agent> --token-stdin   # paste the PAT on stdin (preferred)
+hivectl github set-token <agent> --token <pat>    # inline (visible in shell history)
+```
+
+Either path has hive-c0re delegate the write to hive-priv, which stores the
+file `0600` owned by the agent (so the container can read it) — the same
+credential-injection path as forge/matrix tokens. See
+[hivectl → GitHub](tools/hivectl.md#github).
+
+## Security
+
+- Use a **dedicated bot account**, never a human's.
+- Mint a **minimally-scoped PAT** — only the repos/scopes the agent's
+  workflow needs. Agents have passwordless sudo, so a compromised or
+  hallucinating agent can act as the account within the token's scopes;
+  scope is the real blast-radius limiter, and the container boundary is
+  the enforcement. See [security.md](security.md).
+
+Everything below this point is implementation detail (how the agent
+actually uses the token, and the notification poller's internals).
+
 ## How the agent uses it
 
 When enabled, the container gets:
@@ -53,23 +82,6 @@ simply fail unauthenticated. The token path is baked into the scripts at
 build time (not read from an env var), because claude's Bash tool runs in a
 minimal environment that wouldn't carry one.
 
-## Provisioning
-
-The PAT is operator-supplied. The primary path is the **dashboard
-credentials tab** (github sub-tab): paste the PAT for an agent and submit
-(`POST /api/github-account`). There is also a CLI path for
-recovery/scripting:
-
-```sh
-hivectl github set-token <agent> --token-stdin   # paste the PAT on stdin (preferred)
-hivectl github set-token <agent> --token <pat>    # inline (visible in shell history)
-```
-
-Either path has hive-c0re delegate the write to hive-priv, which stores the
-file `0600` owned by the agent (so the container can read it) — the same
-credential-injection path as forge/matrix tokens. See
-[hivectl → GitHub](tools/hivectl.md#github).
-
 ## Notifications
 
 `hive-github-notify` polls github.com for the agent, turning each unread
@@ -126,12 +138,3 @@ break anything: the poller logs the refusal and stays quiet, and the
 agent simply never gets GitHub wakes. If an agent's GitHub
 notifications never arrive, check the token's scopes first — the
 symptom is silence, not an error.
-
-## Security
-
-- Use a **dedicated bot account**, never a human's.
-- Mint a **minimally-scoped PAT** — only the repos/scopes the agent's
-  workflow needs. Agents have passwordless sudo, so a compromised or
-  hallucinating agent can act as the account within the token's scopes;
-  scope is the real blast-radius limiter, and the container boundary is
-  the enforcement. See [security.md](security.md).