docs: retire the stray top-level web-ui.md, fold it into web-ui/README.md

docs/web-ui.md duplicated the web-ui/ directory name at the top level --
the only such collision in docs/ (every other subsystem has just a
directory, no sibling <dir>.md file). That's exactly why it rendered
outside the directory structure in the docs site nav (mara's report,
hyperhive#4054): the site build walks docs/ generically with no
special-casing, so a loose top-level file next to a same-named
directory shows up as its own flat top-level entry instead of nesting
under that directory's section.

web-ui.md's own first paragraph already said as much -- 'This doc has
been split for readability... start at web-ui/README.md instead.' It
was a leftover pointer from before the split, not a page carrying
unique content on its own merit.

Folded its two sections web-ui/README.md didn't already have (the
swarm-ui design-guide link, and the task-oriented 'reading paths'
quick-lookup list) into web-ui/README.md's existing 'More depth'
section, then deleted the stray file and repointed every real
reference at it: 3 in-tree doc cross-links, 3 doc prose mentions
(retargeted to the more specific dashboard.md/shape.md sub-page each
one was actually about), and ~28 frontend source comments
(dashboard/agent/shared packages) that cited it as
'docs/web-ui.md::<heading>' for implementation context -- retargeted
each to whichever of dashboard.md/shape.md/agent.md actually carries
that heading now, verified against each file's real heading list
rather than guessed.

Verified via scripts/check-doc-refs.sh (the same lint CI runs): 0 dead
pointers, both before write (confirming the tree was clean beforehand)
and after (confirming nothing broke).

docs/agent-lifecycle/approvals.md

@@ -448,7 +448,7 @@ Two visible consequences:
   on every `rebuild_queue_changed` tick), not on the approvals panel
   (which already moved the row to "approved"). A long meta-update
   cascade renders as a parent DAG with one child rebuild per affected
-  agent — see `docs/web-ui.md` for the layout.
+  agent — see `docs/web-ui/dashboard.md` for the layout.
 - **Cancellation**: the dashboard's *× cancel* button on a still-queued
   DAG calls `POST /api/rebuild-queue/{id}/cancel`, which flips it to
   `Cancelled` before any node runs (and fails the approval row instead
@@ -485,7 +485,7 @@ agent.
 
 The dashboard deep-links into this org — a `config repo` link
 per container row and a `review PR on forge` link per config-PR
-approval card. See `docs/web-ui.md`.
+approval card. See `docs/web-ui/dashboard.md`.
 
 ### Submitting agent's view of config repos
 

docs/process/conventions.md

@@ -111,7 +111,7 @@ JSON line-delimited over unix sockets in both directions (host admin
 / manager / agent). SSE streams (`/dashboard/stream` on hive-c0re,
 `/events/stream` on the per-agent web UIs) are `text/event-stream`;
 each frame carries a `seq` field for the snapshot-dedupe dance
-(see `docs/web-ui.md`). Request/response types live in `hive-sh4re`
+(see `docs/web-ui/shape.md`). Request/response types live in `hive-sh4re`
 — change them in one place. The dashboard event vocabulary lives
 in `hive-c0re::dashboard_events::DashboardEvent`.
 

docs/web-ui.md

@@ -1,59 +0,0 @@
-# Web UI
-
-Two web surfaces share the same skeleton: the dashboard (port 7000)
-and the per-agent UIs (each container's port is a deterministic hash
-in :8100-8999 — see
-[`gotchas.md#web-ui-ports-collide-on-hash`](process/gotchas.md#web-ui-ports-collide-on-hash)
-for the mechanics and the collision caveat).
-Both are SPAs — `GET /` returns a static shell, `/api/state`
-returns JSON, JS renders. No full-page reloads.
-
-This doc has been split for readability. Pick the section you need —
-or, if you're the operator looking for how to actually _use_ the
-dashboard rather than how it's built, start at
-**[web-ui/README.md](web-ui/README.md)** instead.
-
-- **[Shape (shared by both)](web-ui/shape.md)** — shared SPA
-  skeleton, SSE multiplexing, terminal pane, listener bind,
-  per-agent relative paths, `data-async` form pattern, side panel,
-  atomic repaint.
-- **[Dashboard layout](web-ui/dashboard.md)** — tab contents
-  (SW4RM, Y3R C4LL, P3RM1SS10NS, SCH3DUL3S) + standalone pages
-  (C0R3 `/core.html`, BU1LDS `/builds.html`, L0GS `/logs.html`,
-  CR3D3NTIALS `/credentials.html`), container row,
-  topology tree, selection bar, approval card, browser
-  notifications, dashboard endpoints + event channel.
-- **[Per-agent page](web-ui/agent.md)** — header, main terminal,
-  composer, side panel + inbox, live view, slash commands,
-  per-agent endpoints, stats page.
-- **[CSS theme variables](web-ui/css-vars.md)** — the Catppuccin
-  Mocha custom properties declared once in `base.css` and the rule
-  that per-page stylesheets reference (never redeclare) them.
-- **[swarm-ui design guide](web-ui/design-guide.md)** — visual
-  language, motion, theming, error-UX, and component-first principles
-  for the swarm-level Preact app specifically (not this doc's
-  dashboard/agent UIs). `/components` on a running swarm-ui is the
-  companion living demo of every primitive it references.
-
-## Reading paths
-
-- **"How does the dashboard SPA stay live without polling?"** →
-  [`web-ui/shape.md`](web-ui/shape.md) (SSE multiplexing,
-  Worker-death self-heal, atomic repaint).
-- **"What does a container row contain?"** →
-  [`web-ui/dashboard.md`](web-ui/dashboard.md) (Container row,
-  Topology tree, Selection bar).
-- **"What endpoints does the dashboard expose?"** →
-  [`web-ui/dashboard.md`](web-ui/dashboard.md) (Dashboard
-  endpoints, Dashboard event channel).
-- **"How does the per-agent terminal render tool calls?"** →
-  [`terminal-rendering.md`](web-ui/terminal-rendering.md) (full row
-  taxonomy + dispatch walkthrough); for a high-level summary see
-  [`web-ui/agent.md`](web-ui/agent.md) (Per-stream rendering).
-- **"What slash commands does the agent accept?"** →
-  [`web-ui/agent.md`](web-ui/agent.md) (Terminal-embedded prompt).
-- **"What are the per-agent HTTP endpoints?"** →
-  [`web-ui/agent.md`](web-ui/agent.md) (Per-agent endpoints).
-- **"Which CSS variable do I use / where are colours defined?"** →
-  [`web-ui/css-vars.md`](web-ui/css-vars.md) (Palette, single-source
-  `base.css` rule).

docs/web-ui/README.md

@@ -85,12 +85,49 @@ that agent's config repo.
 
 ## More depth
 
+Both the dashboard and the per-agent pages are SPAs sharing one
+skeleton: `GET /` returns a static shell, `/api/state` returns JSON,
+JS renders — no full-page reloads.
+
 - **[Dashboard layout](dashboard.md)** — every tab and standalone page,
   in full implementation detail: endpoint shapes, event wiring, exact
   badge-derivation rules.
 - **[Per-agent page](agent.md)** — the per-agent terminal, composer,
   side panel, slash commands, and per-agent endpoints.
 - **[Shape (shared by both)](shape.md)** — the SPA skeleton, SSE
-  multiplexing, and other plumbing shared across every page.
-- **[CSS theme variables](css-vars.md)** — the colour system, for
-  anyone touching the frontend's CSS.
+  multiplexing, terminal pane, listener bind, per-agent relative
+  paths, `data-async` form pattern, side panel, atomic repaint.
+- **[CSS theme variables](css-vars.md)** — the Catppuccin Mocha custom
+  properties declared once in `base.css` and the rule that per-page
+  stylesheets reference (never redeclare) them.
+- **[swarm-ui design guide](design-guide.md)** — visual language,
+  motion, theming, error-UX, and component-first principles for the
+  swarm-level Preact app specifically (not this page's dashboard/agent
+  UIs). `/components` on a running swarm-ui is the companion living
+  demo of every primitive it references.
+
+### Implementation reading paths
+
+Task-oriented jumps straight to the relevant section, for when you're
+touching the code rather than using the UI:
+
+- **"How does the dashboard SPA stay live without polling?"** →
+  [`shape.md`](shape.md) (SSE multiplexing, Worker-death self-heal,
+  atomic repaint).
+- **"What does a container row contain?"** →
+  [`dashboard.md`](dashboard.md) (Container row, Topology tree,
+  Selection bar).
+- **"What endpoints does the dashboard expose?"** →
+  [`dashboard.md`](dashboard.md) (Dashboard endpoints, Dashboard event
+  channel).
+- **"How does the per-agent terminal render tool calls?"** →
+  [`terminal-rendering.md`](terminal-rendering.md) (full row taxonomy
+  and dispatch walkthrough); for a high-level summary see
+  [`agent.md`](agent.md) (Per-stream rendering).
+- **"What slash commands does the agent accept?"** →
+  [`agent.md`](agent.md) (Terminal-embedded prompt).
+- **"What are the per-agent HTTP endpoints?"** →
+  [`agent.md`](agent.md) (Per-agent endpoints).
+- **"Which CSS variable do I use / where are colours defined?"** →
+  [`css-vars.md`](css-vars.md) (Palette, single-source `base.css`
+  rule).

docs/web-ui/agent.md

@@ -1,6 +1,6 @@
 # Per-agent page
 
-> Part of [Web UI](../web-ui.md). See also:
+> Part of [Web UI](README.md). See also:
 > [Shape (shared)](shape.md) · [Dashboard layout](dashboard.md)
 
 

docs/web-ui/dashboard.md

@@ -1,6 +1,6 @@
 # Dashboard layout
 
-> Part of [Web UI](../web-ui.md). See also:
+> Part of [Web UI](README.md). See also:
 > [Shape (shared)](shape.md) · [Per-agent page](agent.md)
 
 

docs/web-ui/shape.md

@@ -1,6 +1,6 @@
 # Shape (shared by both)
 
-> Part of [Web UI](../web-ui.md). See also:
+> Part of [Web UI](README.md). See also:
 > [Dashboard layout](dashboard.md) · [Per-agent page](agent.md)
 
 ## Shared routes