diff --git a/CLAUDE.md b/CLAUDE.md
index 0cb89726..008f7a3b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -209,3 +209,12 @@ with each other.
   thing is, not to how much investigation it took to find it — a
   mechanical fix gets a one-line comment, a genuinely non-obvious
   invariant or decision earns real prose.
+- **Operator-facing doc with real implementation detail mixed in**: wrap
+  the implementation part in a `<details><summary>…</summary>` block
+  (blank line after `<summary>` so the markdown inside still renders,
+  not a second file) rather than splitting into a sibling page — see
+  `docs/integrations/github.md`'s "Implementation" section. Zero nav
+  churn, works uniformly regardless of whether the doc already had a
+  clean boundary. Caveat: it only collapses in a rendered browser —
+  reading the file as raw text (`cat`, the Read tool) shows everything,
+  same as today.
diff --git a/docs/README.md b/docs/README.md
index 78950a78..13cbd9bd 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -55,7 +55,9 @@ declarations.
   [`tools/matrix.md`](tools/matrix.md) for the MCP tool surface and
   `hyperhive.matrixAccounts`.
 - **How do I give an agent a GitHub account (`gh` + `git push`)? How is
-  the PAT injected?** → [`integrations/github.md`](integrations/github.md).
+  the PAT injected?** → [`integrations/github.md`](integrations/github.md)
+  (operator content up top; the `gh`/git-push + notification-poller
+  mechanics are in a collapsed "Implementation" section at the bottom).
 - **What is `/knowledge`? How does the hive-wide knowledge repo sync,
   and how do I contribute a document?** → [`integrations/knowledge.md`](integrations/knowledge.md).
 - **What does `hivectl` do? Provisioning, gateway users, container
diff --git a/docs/integrations/github.md b/docs/integrations/github.md
index 04603978..194ea036 100644
--- a/docs/integrations/github.md
+++ b/docs/integrations/github.md
@@ -57,10 +57,13 @@ credential-injection path as forge/matrix tokens. See
   scope is the real blast-radius limiter, and the container boundary is
   the enforcement. See [security.md](../trust-boundary/security.md).
 
-Everything below this point is implementation detail (how the agent
-actually uses the token, and the notification poller's internals).
+## Implementation
 
-## How the agent uses it
+<details>
+<summary>How the agent's `gh`/`git push` actually authenticate, and how
+the notification poller works</summary>
+
+### How the agent uses it
 
 When enabled, the container gets:
 
@@ -82,7 +85,7 @@ 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.
 
-## Notifications
+### Notifications
 
 `hive-github-notify` polls github.com for the agent, turning each unread
 notification thread into a todo. It is a **separate binary and a
@@ -138,3 +141,5 @@ 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.
+
+</details>