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 <details> section in the same file. Verified empirically (cmark-gfm --unsafe, the website's own render pipeline) that markdown headings nested inside a <details> block still parse as real headings with heading-id anchors once separated from <summary> 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 <details> 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: <details> only collapses in a rendered browser, a raw-text read (cat, the Read tool) still sees everything, same as today.
This commit is contained in:
parent
0824caaa2b
commit
67207ae32f
3 changed files with 21 additions and 5 deletions
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue