First batch of #713 (agent per-container UI prose migration).
Moves 3 substantive WHY-explanations from app.js into
docs/web-ui.md::Per-agent page, replaces each in-code mention
with a brief pointer.
Moved to docs:
- **Terminal-wrap pill anchor** (~11 lines): why the `↓ N new`
pill is anchored in `.agent-main` rather than the default
`.terminal-wrap` parent — backdrop-filter creates a stacking
context, anchoring inside it traps the pill's z-index below the
composer.
- **OAuth code input** (~14 lines across two blocks): masked
password + reveal toggle + `autocomplete="one-time-code"`
rationale (shoulder-surfer / screenshot exposure + WHATWG
semantic value + suppresses browser save-password prompt).
- **NavLink kind resolution + XSS-safe DOM-build** (~8 lines):
Container → same-origin, Forge → `http://<host>:3000<url>`,
External → already absolute; agent-declared strings never reach
innerHTML.
Collapsed in app.js: each block becomes a 3-4 line pointer to the
matching docs section. Drops #262 / #568 / #592 cookies en passant
since their substance now lives in docs. The `#14` cookie on
`historyUrl` / `streamUrl` is also scrubbed — the path-relative
shape is the convention, not an open issue. `#375` (agent.css ID
ref) drops as part of the pill-anchor block collapse since it was
sole-purpose pointing inside that comment.
app.js: 27 → 24 refs. Net ~35 lines of substantive prose moved out
of app.js into docs/web-ui.md::Per-agent page, where it belongs.
mara on PR #775: "this is too much docs in code - move bigger picture
stuff to md files and put refs in code"
New `docs/gateway.md` consolidates the gateway architecture story
that was spreading across long inline comments in `hive-gateway.nix`,
`hive-matrix.nix`, and `hive-forge.nix`:
- vhost map (which URL serves what, which upstream, which option)
- matrix discovery flow (.well-known → sub-domain delegation
sequence)
- Accept-header SPA fallback pattern (#686 / #729 design history)
- local-dev `localHostsEntry` story
- sub-domain rationale (mara verdict tracking) + when sub-path is
right (hyperhive-internal apps)
- per-vhost tuning knobs (forge LFS, matrix long-poll, agent SSE)
- sequencing history (which PR added which routing piece)
In-code comments in the two nix modules get trimmed to short refs
into the doc — keeps the *why* in the markdown while the *what*
stays alongside the code:
- hive-gateway.nix: top-of-file comment, `agentPortsTable`,
`appendHttpConfig`, every location block + vhost
- hive-matrix.nix: `fluffychat-web-fixed`, `fluffychat-web-imaging`,
the dart compile postInstall
README.md gets a new row in the docs table pointing at gateway.md.
Verified `nix eval` still resolves the same vhost + location layout
after the comment trim — no behavioral change, just less in-code
prose.
Mara on #774: previous batches were cookie-stripping rather than
prose migration. This batch actually moves substantive comment
prose from tabs.js into docs/web-ui.md.
Moved to docs/web-ui.md:
- Container row → **Icon layout + load strategy** sub-paragraph
(new): absolute-positioning rationale (so img load state can't
reflow row), fire-and-forget load pattern (no pre-check
reachability), favicon fallback chain, icon-unreachable class,
the immediate-fallback-when-stopped optimisation.
- Container row → **Pending-state derivation** paragraph (new):
three-source priority order (transient → in-flight queue → none),
why ContainerStateChanged isn't enough, the opRunning flag's role
in driving the pending-running class + spinner.
Collapsed in tabs.js:
- Icon block (~14 lines of WHY comments + pointer to docs) →
4-line pointer + behavioural one-liner. Drops #177 / #195 / #202
cookies en passant since their substance now lives in docs.
- Pending-state block (~22 lines split across two paragraphs) →
4-line pointer. Drops #769 self-cookie (the queued vs running
split lives in docs::Container row now).
- SharedWorker EventSource (~7 lines) → 5-line pointer. Drops
#448 cookie (the SSE multiplexing paragraph in docs already
has the design + Firefox throttling rationale; the in-code
comment was duplicating).
- M4TR1X tab gating (~4 lines) → 2-line pointer. Drops #607 cookie
in both tabs.js + docs/web-ui.md::Tab strip (the substance was
already in docs, just had the cookie attached).
tabs.js: 11 → 6 refs (92% reduction from baseline 73). Net effect:
~47 lines of substantive prose moved out of tabs.js into
docs/web-ui.md, where it belongs.
#437 (multi-step progress on rebuild_queue entries — closed) ×2:
in tabs.js current-step comment + in docs/web-ui.md prose
referencing the phase annotation.
#501 (PR — merged for #437) ×1: paired with #437 in the same
tabs.js current-step comment.
#575 (X button to cancel pending builds — closed) ×2: in tabs.js
cancel-form comment + in docs/web-ui.md cancel-button prose.
#436 (route approval execution through rebuild_queue — closed)
×1 in docs/web-ui.md: scrubbed the parenthetical "; #436" next
to the approval source-chip description (small freebie since I
was editing that paragraph anyway). The approval-as-source-chip
is the implementation of #436; the cookie was just history.
Pre-scanned docs for matching cookies; caught all 3 doc cookies
in the same PR.
Container row's pending highlight fired for both queued + running
rebuild-queue entries, so a long queue painted half the SW4RM tab
amber. Mara on #769: don't highlight while queued, show running as
spinner on agent icon.
- tabs.js: derive opRunning (transient OR op.state === 'running')
separately from pending; add a pending-running row class.
Operator-initiated transients still count as running so the
rebuild-now-clicked → backend-picks-it-up window stays visually
consistent.
- dashboard.css: move the amber border + tint from .pending to
.pending-running (queued rows now keep their normal look, with
the badge text still saying "rebuild queued"). Add a 1s linear
rotating amber arc as .pending-running > .container-icon::after,
with overflow:visible so the ring sits just outside the icon and
composes with the mauve selected ring.
- docs/web-ui.md::Container row: describe the queued vs running
split in prose. Drop the orphaned (#398) cookie while I'm at it
— small #712 freebie.
#272 (show approval requested-at — closed) ×2 in tabs.js (live
ApprovalAdded fallback note + amber stale chip comment) + ×1 in
docs/web-ui.md (Approval card identity header). #275 (select all
for meta inputs — closed) ×1 in tabs.js (bulk-select rationale)
+ ×1 in docs/web-ui.md (M3T4 1NPUTS tree control note). The
amber-stale chip line in tabs.js now points at
docs/web-ui.md::Approval card for the rendered spec instead of
the closed issue.
Same theme as the tabs.js scrubs in this batch — drop the 7 #NNN
cookies (#444, #459, #460, #467, #474, #535, #564) the SCH3DUL3S
section was carrying. The substantive prose stands on its own;
the citations were just attribution tracking that belongs in the
git log + issue threads, not the user docs.
Mara on #744: 'no docs md changes needed?' — yes, this.
turn-loop.md: add optional hive_name / swarm_name fields to get_agent_meta
response shape; note they are omitted when the host options are unset.
CLAUDE.md: update hive-gateway.nix entry to mention per-agent routing
and .well-known; drop stale #609 cookie.
turn-loop.md:
- expand stale '{label} and {operator_pronouns}' note to all 5
current placeholders (#730 added hive_identity + swarm_identity)
- add 200-char + single-line validation note to set_status (#723)
mara's review nit: explaining the absence of a manager special-case
implicitly endorses the idea that special cases would be normal.
Default is no special case; the doc shouldn't dwell on it.
- ST0P comment block removed entirely (the bulk-button line above
is self-explanatory; the substantive 'c0re survives manager-down'
rationale lives in the host docs, not here).
- M0V3 helper comment reframed: trim the 'no special-case' framing
but keep the substantive note that the backend refuses moves it
can't satisfy and the failure surfaces in the bulk roll-up.
- docs/web-ui.md::Selection bar bullet list: drop the 'manager
included; no special-case' qualifiers; just describe the action.
M0V3→ROOT keeps the rationale that backend refusals surface in
the roll-up but stops calling out manager specifically.
selection + selection-bar in tabs.js carried six #443 cookies + two
#596 cookies — most marking the bulk-bar architectural decision
('actions live in bar, not on per-card buttons; manager not
special-cased') or the SW4RM-tab gate. All scrubbed; the canonical
docs/web-ui.md::Selection bar section already covered the bulk
actions in detail but was missing a preface for the **interaction
model** itself (how selection enters/exits, why per-card buttons
moved). Added that as the opening paragraph of the section so the
in-code refs have something to point at.
Net in this batch:
- tabs.js: -8 #NNN refs (#443 ×6, #596 ×2)
- docs/web-ui.md: +9 lines (interaction-model preface)
- functional code unchanged; build clean
refs #712
Per mara on #14: 'make agent page not assume root path, links / api
calls need to be relative'. atlas's nginx side (#15) will mount the
per-agent UI at a prefix like /agent/<name>/ instead of its own
port; for the page to keep working under that prefix, every
in-page reference needs to resolve document-relative rather than
root-anchored.
Converted in this pass:
- HTML <link>/<script>/<img>/<a> hrefs in index.html, stats.html,
screen.html: '/icon' → 'icon', '/static/agent.css' →
'static/agent.css', back links '/' → './'.
- app.js fetch() targets ('/api/state' → 'api/state', /api/cancel,
/api/loose-ends, etc.), form actions ('/login/start', '/send'),
EventSource urls ('/events/stream', '/events/history').
- stats.js fetch() targets.
- screen.html WebSocket URL: was hardcoded as
ws(s)://host/screen/ws; now derived from document.baseURI via
new URL('screen/ws', document.baseURI) so the gateway prefix
flows through.
Slash-command labels (/cancel, /compact, …) and the dashboard-port
link (different port, intentionally absolute) intentionally
untouched.
Added a new 'Per-agent relative paths' section to docs/web-ui.md
covering the rationale + the trailing-slash gotcha (sub-pages like
/stats must NOT have a trailing slash, or 'static/app.js' resolves
under /stats/ instead of replacing the segment).
Functional code unchanged; build clean. Damocles + atlas can
proceed with the backend / nginx side without depending on this
landing first, but once both ship the agent page works under the
gateway-prefixed URL without further changes.
refs #14
Two threads cleaned up in tabs.js:
1. Top-of-file '#406 step 1/2/3' historical narrative deleted —
it documented past module splits (moves to common.js / flow.js,
file rename app.js → tabs.js) which are git-history concerns,
not current-behaviour docs. Replaced with a two-sentence
contract description that references docs/web-ui.md and the
present-tense module split.
2. Five 'moved to ./common.js (#406)' stubs deleted — same
reasoning. The imports at the top of the file already document
what's in common.js; standalone 'this function lives elsewhere'
pointers are noise once you stop tracking the move event.
paintAtomic's substantive rationale migrated to a new
'Atomic section repaint' subsection in docs/web-ui.md (under the
existing focus-preservation note); in-code comment shrinks to a
two-line reference. Same pattern as the topology-tree batch.
Net: 36 fewer lines in tabs.js, 14 new in docs/web-ui.md.
Functional code unchanged; build clean.
refs #712
First slice of #712 (dashboard SPA frontend → docs/). Shrinks the
buildAgentTree + treePrefixDom comment blocks in tabs.js to one-line
docs/ references; adds a new 'Topology tree' subsection to
docs/web-ui.md under '### Container row' carrying the substantive
prose.
Net effect on this region:
- 6 #NNN tracking cookies dropped (#363, #361, #388)
- 30 lines of substantive design comments collapsed to 6 lines of
references in tabs.js
- 35 new lines in docs/web-ui.md (the migrated prose, restructured
into a single coherent subsection rather than two adjacent comment
blocks)
- functional code unchanged; build clean
Deliberately small pattern-check (one cohesive subsystem) before
expanding to the rest of #712 (~140 more refs across tabs.js +
dashboard.css + index.html + common.js + flow.js). Reviewers can
sanity-check the shape (where prose lands, how short the in-code
ref becomes, whether section nesting reads well) before I scale.
refs #712
turn-loop.md:
- remove stale "Agent-only today" note from hive wake (fixed by #698)
- add <parent> sentinel to send tool description (added by #703)
gotchas.md:
- add systemd.services.*.path /bin auto-append gotcha (hit by #672/#705)
Two changes from mara's review:
1. drop the manager special-case. Both M0V3 affordances now apply
regardless of whether the manager is in the selection; backend
topology::set_parent refuses the manager move and the failure
surfaces in the bulk-action error roll-up. Matches the #443 ST0P
policy of 'don't pre-gate manager actions, let the backend speak'.
2. enable the M0V3 → <pick> picker for multi-select. Was single-agent
only in v1. Picker now omits every selected agent itself plus the
union of every selected agent's descendants (cycle-safe across the
whole batch); on submit POSTs once per selected agent sequentially,
same shape as the existing bulk-button loop. Confirm message +
error roll-up adapt to selection size.
docs/web-ui.md updated to match.
Backend POST /api/topology/set-parent already shipped; the dashboard
was missing the operator surface to drive it. Adds two affordances
to the SW4RM tab's selection bar (alongside the existing R3ST4RT /
ST0P / ST4RT / R3BU1LD / DESTR0Y / PURG3 actions):
- '⇡ M0V3 → ROOT' (bulk): promote selected agents to top-level
(parent=null). Disabled when all selected are already at root or
the selection includes the manager (backend refuses anyway).
- '⇢ M0V3 → [pick]' (single-agent only): inline <select> dropdown
+ button pair. Dropdown lists every container that isn't the
target nor a descendant of it (client-side BFS via the existing
c.parent map). On submit POSTs form-encoded
'child=<name>&new_parent=<target>' to /api/topology/set-parent;
the backend re-checks the cycle invariant and re-emits a
container snapshot so the tree repaints without a reload.
Both POSTs hit a single URL, so addBulkButton grew an optional
'perAgentBodyFor(name)' hook to handle the body-driven endpoint
shape (vs the URL-suffix /start/<name> shape every other action
uses). Lifecycle endpoints unchanged.
Mauve chrome (var(--mauve)) reads as 'structural change' rather
than the destructive red / amber of destroy / rebuild.
closes#486
Loose-ends endpoint only carries pending state — a question
disappearing from the list can mean answered, cancelled by asker,
or TTL expired. Previous [answered ✓] glyph implied successful
operator response across all three paths.
Rename .ask-answered-tag → .ask-resolved-tag and use the neutral
[resolved] label. Full resolution detail (who answered with what)
remains visible via the question's history in the side panel.
Addresses argus review note on #668.
When an agent calls mcp__hyperhive__ask with to==operator (the
default), the rich tool-use renderer now mounts an empty
ask-answer-inline-slot inside the expanded ask row and enqueues a
loose-ends refresh. A new reconcileAskBinds() walks waiting slots
on every loose-ends update, matches each against pending
operator-bound questions by question text, and injects the same
inline answer form the side panel uses (buildAnswerForm → POST to
the host dashboard answer-question endpoint). When a question
resolves, the form gets replaced by a struck-through [answered ✓]
tag so the scrollback reflects the closed state.
Lets the operator respond to agent questions inline in the live
terminal without context-switching to the loose-ends side panel or
the dashboard Y3R C4LL tab.
Refreshes loose-ends both on tool_use render (best-effort, may
miss the question before the broker persists it) and on the
matching tool_result (the right moment — MCP has just returned the
assigned id). Slots are pruned on /clear and defensively filtered
for isConnected on each reconcile.
closes#666
Per [mara on PR #615 comment 7349](http://localhost:3000/hyperhive/hyperhive/pulls/615#issuecomment-7349):
> follow nix conventions, services.hyperhive it is. the earlier we
> change this, the less breakage.
Renames the entire host-side option tree under `services.hyperhive.*`:
- `services.hive-c0re.*` → `services.hyperhive.c0re.*`
- `hyperhive.enable` → `services.hyperhive.enable`
- `hyperhive.domain` → `services.hyperhive.domain`
- `hyperhive.forge.*` → `services.hyperhive.forge.*`
- `hyperhive.matrix.*` → `services.hyperhive.matrix.*`
Per mara's "earlier = less breakage", the previous `services.hive-c0re.enable`
deprecation alias is dropped. Operators get a clear eval error on the
old paths pointing at the rename. Single migration moment.
Per-agent options in `nix/templates/harness-base.nix` (`hyperhive.model`,
`hyperhive.allowedRecipients`, etc.) stay at `hyperhive.*` — they're
container-level config, not services in the NixOS sense.
Verified via `nix flake check --no-build` + an end-to-end NixOS eval
exercising every renamed path.
Follow-up needed: rust source comments referencing the old NixOS
option names (`hive-c0re/src/{meta,coordinator,main,dashboard}.rs`)
should be updated in a separate pure-rust PR to keep this one
strictly nix-only.
- Move options.services.hive-c0re → options.hyperhive.c0re
- Add options.hyperhive.enable to auto-enable c0re + subsystems
- Add deprecation alias for services.hive-c0re.enable (backward compat)
- Update doc references in README, flake.nix, docs, harness-base.nix
- Simplifies config: 'hyperhive.enable = true' now enables everything
Existing operator configs using services.hive-c0re.enable will
continue to work but emit a deprecation warning. Aligns the option
namespace with the existing hyperhive.* family (matrix, forge, domain).
fixes#612
Frontend half of #607 v0 — adds the `◆ M4TR1X ◆ →` page-link entry
to the dashboard tab strip between SCH3DUL3S and FL0W →. Same
`tab-link` class as FL0W → since /matrix/ is its own SPA, not an
in-place pane swap.
Hidden via the `hidden` attribute by default; tabs.js's `refreshState`
flips it based on `s.matrix_gui_enabled` (added in #610). When the
operator hasn't set `hyperhive.matrix.gui.enable = true` the snapshot
returns false and the tab strip doesn't surface a dead link.
docs/web-ui.md updated:
- chrome-header tab-strip list now includes M4TR1X → with the
hidden-when-disabled note
- new "M4TR1X page" section under FL0W explaining the same-origin
serve via hive-c0re ServeDir + the manual homeserver URL pick on
first login (with #609 tracking the post-#15 nginx-front re-root +
.well-known/matrix/client auto-discovery)
