From 67207ae32f8c33b5afbd577eaa22574e331941a9 Mon Sep 17 00:00:00 2001 From: iris Date: Wed, 2 Sep 2026 19:48:14 +0200 Subject: [PATCH] docs: pilot split of github.md into operator-facing + collapsed implementation hyperhive#3902, mara: option (a) - a content pass splitting mixed docs into operator-facing content plus implementation detail. One file first, to agree on the split pattern before doing the other ~19. Went through 3 shapes on review before landing here: a sibling -internals.md file (mara: clutters the navigation), then two tree-precedent alternatives damocles raised (subdir+README like web-ui/; or only split docs with a pre-existing boundary marker, which would've covered 3-4 of the ~20 flagged docs and left the rest untouched), then mara's own proposal - a collapsed
section in the same file. Verified empirically (cmark-gfm --unsafe, the website's own render pipeline) that markdown headings nested inside a
block still parse as real headings with heading-id anchors once separated from by a blank line, so anchor links into the collapsed section keep working. github.md keeps enabling/provisioning/security up top; its 'Implementation' section is now a
block holding what was briefly a separate github-internals.md (deleted again) - how the agent's gh/git-push actually authenticate, and the notification poller's internals. Reverted the two cross-references + the docs/README.md entry back to pointing at github.md now that the content lives there again. Added a short CLAUDE.md note recording the pattern per mara's ask, including the one real caveat damocles flagged:
only collapses in a rendered browser, a raw-text read (cat, the Read tool) still sees everything, same as today. --- CLAUDE.md | 9 +++++++++ docs/README.md | 4 +++- docs/integrations/github.md | 13 +++++++++---- 3 files changed, 21 insertions(+), 5 deletions(-) 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 `
…` block + (blank line after `` 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 +
+How the agent's `gh`/`git push` actually authenticate, and how +the notification poller works + +### 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. + +