mara/hyperhive
mara/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Activity

docs: move implementation sections out of the handbook pages

Browse source 
Three handbook pages carried sections an operator never reads, named after
source paths and build internals. They move to pages under 4-implementation,
and each handbook page keeps a short pointer.

- forge.md: the notification poller (what it polls, how it formats,
  de-duplicates and marks notifications read) is now
  agent-tools/forge-notify.md. The forge page keeps a short Notifications
  section.
- matrix.md: the retired hive-side matrix code, the evaluation assertions and
  the fluffychat-web build fixes are now networking/matrix-homeserver.md.
- github.md: the Implementation section (how `gh` and `git push`
  authenticate, and the GitHub poller) is now agent-tools/github.md.

docs/README.md and the agent-tools README list the new pages, and AGENTS.md's
note on mixed operator and implementation docs now says to move the detail
and leave a pointer.
This commit is contained in:
iris 2026-11-07 11:49:28 +01:00 • committed by mara
commit 97671e28d5
1 changed files with 504 additions and 466 deletions
Download patch file Download diff file Expand all files Collapse all files

18
AGENTS.md
View file

@ -222,10 +222,14 @@ in this file and drifted.
mechanical fix gets a one-line comment, a genuinely non-obvious
invariant or decision earns real prose. Don't restate a module's `//!`
doc in a comment further down the same file.
- **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 renders) rather
than a sibling page — see `docs/2-handbook/external-accounts/github.md`'s
"Implementation" section. It only collapses in a rendered browser, and
the `<summary>` line isn't markdown-processed, so keep it plain prose
with no backticks.
- **Operator-facing doc with implementation detail mixed in**: a section
of source paths, wire formats or build internals belongs on a page under
`docs/4-implementation/`, with a short pointer left in the handbook page
(see how `docs/2-handbook/swarm/forge.md` points to
`docs/4-implementation/agent-tools/forge-notify.md`). A short aside that
an operator may want but most do not goes in a
`<details><summary>…</summary>` block (blank line after `<summary>` so the
markdown inside renders), as in `docs/2-handbook/swarm/schedules.md`'s
"Implementation" section. It only collapses in a rendered browser, and the
`<summary>` line isn't markdown-processed, so keep it plain prose with no
backticks.