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/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