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

docs: the handbook follows the three layers: swarm, hives, agents

Browse source 
The handbook's sections were agent-lifecycle, integrations, swarm, tools,
trust-boundary and web-ui, which do not follow how the system is built, so a
reader could not tell which layer a page is about. Its pages now sit in
swarm/, hives/ and agents/, with the accounts an agent can hold outside the
system in external-accounts/.

- swarm/: forge, matrix and the knowledge repo join the swarm pages, and so
  does the swarmctl reference.
- hives/: the dashboard, hivectl and its reference, and the operator/agent
  boundary, with a README that takes over the old web-ui and tools pages.
- agents/: the roster, persistence, config changes, the agent's own web page
  (was web-ui/agent) and the security model, with a README.
- external-accounts/: GitHub and GitLab.

Pages are moved whole; none is split yet. Every reference follows: relative
links in the docs, `docs/2-handbook/...` paths in code comments, the nix
checks that regenerate the CLI references and the ignore list, and docs/README.md,
whose handbook section is now by layer.
This commit is contained in:
iris 2026-11-07 11:20:48 +01:00 • committed by mara
commit 0e84fe8bc4
4 changed files with 393 additions and 363 deletions
Download patch file Download diff file Expand all files Collapse all files

20
frontend/packages/dashboard/src/agents.js
View file

@ -1,7 +1,7 @@
// 4G3NTS (containers) domain — extracted from tabs.js.
// Agent topology, container-row rendering, selection bar, and all
// live-update apply handlers for container-state, transient, and
// job-queue-rollup ops. See docs/2-handbook/web-ui/dashboard.md::Container row for the
// job-queue-rollup ops. See docs/2-handbook/hives/dashboard.md::Container row for the
// rendering contract.
import { $, form, fmtAgeSecs } from "./common.js";
@ -37,14 +37,14 @@ const containerRowCache = new Map();
// by agent name -> Map<transient_kind, since_unix>: an agent can hold
// several pills at once (every *running* node naming the agent lights
// one now, not just a curated "worth surfacing" subset — see
// docs/2-handbook/web-ui/dashboard.md::Container row), keyed the same way the backend's
// docs/2-handbook/hives/dashboard.md::Container row), keyed the same way the backend's
// own tombstone map is, `(agent, label)`, so a clear only removes the
// specific pill it names rather than guessing. `since_unix` is
// wall-clock so the elapsed-seconds badge ticks without polling.
const transientsState = new Map();
// In-memory set of selected agent logical names backing the sticky
// #selection-bar. See docs/2-handbook/web-ui/dashboard.md::Selection bar for the
// #selection-bar. See docs/2-handbook/hives/dashboard.md::Selection bar for the
// interaction model (icon-click toggle, Esc/clear button drop,
// tab-gated visibility).
const selectionState = new Set();
@ -225,7 +225,7 @@ function derivePortConflicts(containers) {
}
// ─── container ordering ──────────────────────────────────────────────────────
// Flat alphabetical sort — see docs/2-handbook/web-ui/dashboard.md::C0NTAINERS.
// Flat alphabetical sort — see docs/2-handbook/hives/dashboard.md::C0NTAINERS.
function sortedContainerRows(containers) {
// Close any open context menu before replacing the DOM tree — the
@ -285,7 +285,7 @@ function buildContainerLi(c, opts) {
// Agent icon: 5em square wrapper with an absolutely-positioned
// <img> + fire-and-forget load with /favicon.svg fallback. The
// wrapper doubles as the selection toggle (click / keyboard).
// See docs/2-handbook/web-ui/dashboard.md::Container row for the layout + load-strategy
// See docs/2-handbook/hives/dashboard.md::Container row for the layout + load-strategy
// rationale.
const iconImg = el("img", { class: "container-icon-img", alt: "" });
const icon = el(
@ -478,7 +478,7 @@ function buildContainerLi(c, opts) {
// dashboard-state fetch above.
if (pending.length) {
// One badge per pill — an agent can carry several transients at
// once now (see docs/2-handbook/web-ui/dashboard.md::Container row), each rendered
// once now (see docs/2-handbook/hives/dashboard.md::Container row), each rendered
// independently rather than collapsed into one label.
for (const label of pending) {
head.append(
@ -561,7 +561,7 @@ function buildContainerLi(c, opts) {
// Per-card action buttons (R3ST4RT / ST0P / ST4RT / R3BU1LD /
// DESTR0Y / PURG3) live on the selection bar, not here — see
// docs/2-handbook/web-ui/dashboard.md::Selection bar. The contextual `needs update ↻`
// docs/2-handbook/hives/dashboard.md::Selection bar. The contextual `needs update ↻`
// chip in the head row stays — it's a state-hint, not an
// action button.
@ -632,7 +632,7 @@ export function renderContainers(s) {
// TCP fallback — the gateway proxies the prefix to the per-agent
// harness (unix-domain via `agent-sockets.json`, or a computed TCP
// loopback port while the socket marker is absent). See
// `docs/2-handbook/web-ui/dashboard.md::Container row` + `docs/4-implementation/networking/gateway.md::Vhost map`.
// `docs/2-handbook/hives/dashboard.md::Container row` + `docs/4-implementation/networking/gateway.md::Vhost map`.
const gatewayLinks = !!(s && s.gateway_enabled);
// Forge public URL: state.forge_public_url (set by the NixOS module
// from services.hyperhive.swarm.forge.publicUrl) or null — never guessed
@ -658,7 +658,7 @@ export function renderContainers(s) {
// full stop (mara, on review: "remove the per agent pending stuff -
// only show what is running"; rendered one badge per pill — mara,
// earlier: "show all running nodes that name the agent"). See
// docs/2-handbook/web-ui/dashboard.md::Container row.
// docs/2-handbook/hives/dashboard.md::Container row.
const transientKindsMap = transientsState.get(c.name);
// Sorted for stable badge order across renders — Map iteration
// order is insertion order, which shifts as pills clear/re-add.
@ -725,7 +725,7 @@ export function renderContainers(s) {
// ─── selection bar ───────────────────────────────────────────────────────────
// Sticky-bottom strip; visible when >=1 agent selected on the 4G3NTS
// tab. See docs/2-handbook/web-ui/dashboard.md::Selection bar for the interaction model
// tab. See docs/2-handbook/hives/dashboard.md::Selection bar for the interaction model
// and the per-action availability rules (disabled-with-tooltip for
// actions that don't apply to the full selection). Actions POST per
// agent in a loop (endpoints are individually idempotent /

2
frontend/packages/dashboard/src/common.css
View file

@ -247,7 +247,7 @@ code {
}
/* M0V3 affordance (selection bar) — mauve reads as "structural
change" rather than the destructive red / amber chrome of
destroy / rebuild. See docs/2-handbook/web-ui/dashboard.md::Selection bar. */
destroy / rebuild. See docs/2-handbook/hives/dashboard.md::Selection bar. */
.btn-move {
color: var(--purple);
border-color: var(--purple);

2
frontend/packages/dashboard/src/dashboard.css
View file

@ -12,7 +12,7 @@
/* ─── tabbed dashboard chrome ──────────────────────────────────────
Top-of-page sticky header with banner + tab strip. SSE stays
alive across tab switches. See docs/2-handbook/web-ui/dashboard.md::Chrome header + Tab strip for the
alive across tab switches. See docs/2-handbook/hives/dashboard.md::Chrome header + Tab strip for the
routing model. */
body.dashboard-shell {

2
frontend/packages/dashboard/src/index.html
View file

@ -165,7 +165,7 @@
<!-- Selection action bar. Sticky-bottom strip that slides into
view when one or more agent cards is selected (click the icon
to toggle). See docs/2-handbook/web-ui/dashboard.md::Selection bar for the bulk
to toggle). See docs/2-handbook/hives/dashboard.md::Selection bar for the bulk
action gating + clear semantics. -->
<div
id="selection-bar"