docs: sort the top-level directories into five sections by what the reader wants

Every docs directory moves under 1-getting-started, 2-handbook,
4-implementation or 5-project; the options reference (section 3) comes from
the website and has no directory here. trust-boundary stays whole under the
handbook for now. web-ui, swarm and tools split between handbook and
implementation, and the command-line references move to
2-handbook/reference. Links, path references in code and nix, and the docs
index follow the moves; no page content changes.

frontend/packages/shared/src/badge/Badge.tsx

@@ -17,7 +17,7 @@
 // them with no real distinction to justify it. Lives in `shared` because both
 // swarm-ui *and* the per-agent page need the interactive shape, and
 // `shared` is the one package both already depend on (see
-// `docs/web-ui/design-guide.md`'s component-first + junk-drawer rules).
+// `docs/5-project/web-ui/design-guide.md`'s component-first + junk-drawer rules).
 import type { ComponentChildren } from "preact";
 import "./Badge.css";
 

frontend/packages/shared/src/base.css

@@ -2,7 +2,7 @@
    web UI. The colour variables it references (`--bg`, `--fg`, …) live in
    the standalone `theme.css` (Catppuccin Mocha), linked separately by
    every page BEFORE this file so the `:root` vars resolve — see
-   `theme.css` + docs/web-ui/css-vars.md. Per-page stylesheets append on
+   `theme.css` + docs/4-implementation/web-ui/css-vars.md. Per-page stylesheets append on
    top of this and must NOT redeclare the colour variables; `theme.css`
    is the one source of truth. */
 body {

frontend/packages/shared/src/colors.css

@@ -9,7 +9,7 @@
    Kept as its own standalone stylesheet (not @import-ed into theme.css)
    so a swap replaces just this file — `theme.css` and the page bundles
    stay untouched. Every page links this BEFORE `theme.css`. See
-   docs/web-ui/css-vars.md.
+   docs/4-implementation/web-ui/css-vars.md.
 
    Two raw palettes, one declaration each — `--mocha-baseNN` (dark,
    Catppuccin Mocha) and `--latte-baseNN` (light, Catppuccin-Latte-

frontend/packages/shared/src/dropdown/Dropdown.tsx

@@ -2,7 +2,7 @@
 // the `Badge` that opened it (../badge/Badge.tsx) so the control is
 // visually attached to the thing it affects, instead of living three
 // clicks away in a catch-all menu (the junk-drawer pattern
-// `docs/web-ui/design-guide.md` calls out by name). Not a native `<dialog>` — a
+// `docs/5-project/web-ui/design-guide.md` calls out by name). Not a native `<dialog>` — a
 // `showModal()` dialog's backdrop would visually detach it from its
 // anchor badge, and a non-modal `show()` gets no click-outside-to-close
 // for free, so this hand-rolls the same "outside click or Escape

frontend/packages/shared/src/prefs.ts

@@ -12,7 +12,7 @@ const EXPAND_DETAILS_KEY = "hive-agent-expand-details";
 // (long tool-results, Write/Edit diffs, …) should default open. Pure
 // client-side — no backend field, nothing round-trips through
 // `/api/*`. Read live (not cached) by the shared terminal factory's
-// `expandDetails` option — see docs/web-ui/shape.md::Shared terminal
+// `expandDetails` option — see docs/4-implementation/web-ui/shape.md::Shared terminal
 // pane — so a preference change applies to the next rendered row in
 // any already-open agent tab without a reload.
 export function getExpandDetailsPref(): boolean {
@@ -34,7 +34,7 @@ export function setExpandDetailsPref(v: boolean): void {
 const HIDE_DEBUG_KEY = "hive-agent-hide-debug";
 
 // Whether a per-agent terminal's `debug`-level rows (thinking, coalesced
-// ticks, ambient harness chatter — see docs/web-ui/terminal-rendering.md's
+// ticks, ambient harness chatter — see docs/4-implementation/web-ui/terminal-rendering.md's
 // Levels table) should be skipped entirely rather than rendered muted.
 // Same shape as `getExpandDetailsPref` above: pure client-side, no
 // backend field, read live (not cached) so a change applies to the next

frontend/packages/shared/src/side-panel/hive-side-panel.js

@@ -31,7 +31,7 @@ import { el } from "../dom.js";
 import { attachShadowCss } from "../shadow-css.js";
 import sidePanelCss from "./hive-side-panel.css";
 
-// See docs/web-ui/agent.md::Side panel for the hit-strip + pointer-capture +
+// See docs/2-handbook/web-ui/agent.md::Side panel for the hit-strip + pointer-capture +
 // localStorage persistence model; CSS clamps the stored value to min
 // 320px / max 96vw and out-of-range stored values are dropped silently.
 // Shared by both packages deliberately — see module header.

frontend/packages/shared/src/tabs/tabs.css

@@ -6,7 +6,7 @@
    so this inherits theme-swap safety for free. Call sites keep a thin
    variant class for size/spacing deltas; richer affordances (count
    pills, the dashboard's responsive overflow ⋮ menu) layer on top in the
-   per-page CSS. See docs/web-ui/css-vars.md. */
+   per-page CSS. See docs/4-implementation/web-ui/css-vars.md. */
 
 .hive-tabbar {
   display: flex;

frontend/packages/shared/src/tabs/tabs.js

@@ -15,7 +15,7 @@
 //
 // On show: toggles `.hive-tab--active` + `aria-selected` on each control
 // and `hidden` on each panel, then fires `onShow(id)` for per-tab
-// side-effects (lazy loads, etc.). See docs/web-ui/css-vars.md.
+// side-effects (lazy loads, etc.). See docs/4-implementation/web-ui/css-vars.md.
 
 /**
  * @param {Element|null} tabbar  container holding the `[data-tab]` controls

frontend/packages/shared/src/terminal/terminal.css

@@ -13,8 +13,8 @@
 
    No `.term-input` here — composers are a separate concern, owned by
    each page's own CSS. Row taxonomy + layout contract documented in
-   `docs/web-ui/shape.md::Shared terminal pane` and
-   `docs/web-ui/terminal-rendering.md`. */
+   `docs/4-implementation/web-ui/shape.md::Shared terminal pane` and
+   `docs/4-implementation/web-ui/terminal-rendering.md`. */
 
 .terminal-wrap {
   position: relative;
@@ -154,7 +154,7 @@
    is now four: the four severities every row already carries. Structural
    identity (this is a turn boundary, this is a tool call) is carried by
    the row's icon (`◆`, `🔧`, `✅`, …) and summary text instead of colour —
-   see docs/web-ui/terminal-rendering.md. */
+   see docs/4-implementation/web-ui/terminal-rendering.md. */
 .live .level-debug {
   color: var(--muted);
 }

frontend/packages/shared/src/terminal/terminal.js

@@ -5,14 +5,14 @@
 //
 // create(opts) — full options list + renderer api (api.row, api.details,
 //   api.detailsDiff, api.placeholder, api.fromHistory) + behavioral notes:
-//   docs/web-ui/shape.md §Shared terminal pane.
+//   docs/4-implementation/web-ui/shape.md §Shared terminal pane.
 
 const NEAR_BOTTOM_PX = 48;
 // Scroll distance from the top of the log that triggers an automatic
 // "load older" fetch — fires via the scroll event handler so the operator
 // never has to click the pill; the pill stays as a visual indicator.
 const LOAD_MORE_SCROLL_PX = 80;
-// Snap-to-bottom animation duration. See docs/web-ui/shape.md::Shared
+// Snap-to-bottom animation duration. See docs/4-implementation/web-ui/shape.md::Shared
 // terminal pane (Sticky-bottom + snap animation) for the 140ms-vs-
 // 500ms-browser-default + 24px short-circuit rationale.
 const SCROLL_ANIM_MS = 140;
@@ -46,7 +46,7 @@ export function create(opts) {
   // operator-driven wheel/drag stay in sync.
   let stickToBottom = true;
   // Scroll-handler gate during in-flight snap animations — see
-  // docs/web-ui/shape.md::Shared terminal pane (Mid-animation scroll-event
+  // docs/4-implementation/web-ui/shape.md::Shared terminal pane (Mid-animation scroll-event
   // guard) for the eased-through-not-near-bottom rationale.
   let smoothScrollingUntil = 0;
   // rAF id for the current snap animation. Cancelled when a new
@@ -62,7 +62,7 @@ export function create(opts) {
   // Snap the log to the bottom with a brief eased animation. Cancels
   // any in-flight frame loop so back-to-back snaps coalesce; falls
   // back to instant scroll during `currentNoAnim` backfill replay
-  // or under SCROLL_SNAP_PX. See docs/web-ui/shape.md::Shared terminal pane.
+  // or under SCROLL_SNAP_PX. See docs/4-implementation/web-ui/shape.md::Shared terminal pane.
   function snapToBottom(immediate) {
     stickToBottom = true;
     if (scrollAnimRaf) {
@@ -128,7 +128,7 @@ export function create(opts) {
     // immediately so the MutationObserver stops re-firing snapToBottom()
     // and the animation-guard window can expire naturally. Without this,
     // live events arriving < 220ms apart permanently block scroll-to-top
-    // and loadMore() never fires. See docs/web-ui/shape.md::Shared terminal
+    // and loadMore() never fires. See docs/4-implementation/web-ui/shape.md::Shared terminal
     // pane (Mid-animation scroll-event guard).
     const inAnim = Date.now() < smoothScrollingUntil;
     const nearBottom = isNearBottom();
@@ -156,7 +156,7 @@ export function create(opts) {
   });
   // Post-append mutation snap — catches renderer mutations that land
   // after `api.row` returns (badges, multi-line bodies, tool
-  // panes). See docs/web-ui/shape.md::Shared terminal pane (Post-append
+  // panes). See docs/4-implementation/web-ui/shape.md::Shared terminal pane (Post-append
   // MutationObserver) for why the pre-append `afterAppend` hop
   // alone isn't enough.
   const mo = new MutationObserver(() => {
@@ -165,7 +165,7 @@ export function create(opts) {
   mo.observe(log, { childList: true, subtree: true, characterData: true });
 
   // Pre-append nearBottom snapshot drives the initial snap decision —
-  // see docs/web-ui/shape.md::Shared terminal pane (Post-append
+  // see docs/4-implementation/web-ui/shape.md::Shared terminal pane (Post-append
   // MutationObserver) for why we need both this and the MO.
   function afterAppend(wasNearBottom) {
     if (currentNoAnim || wasNearBottom) {
@@ -452,7 +452,7 @@ export function create(opts) {
     // Optional streamFactory(url) → EventSource-shaped facade. Lets
     // the dashboard hand the factory a SharedWorker-backed source so
     // open hyperhive tabs share one upstream — see
-    // docs/web-ui/shape.md::Shared terminal pane (Backfill + SSE). Default
+    // docs/4-implementation/web-ui/shape.md::Shared terminal pane (Backfill + SSE). Default
     // falls back to `new EventSource(url)`.
     const es = opts.streamFactory
       ? opts.streamFactory(opts.streamUrl)
@@ -584,7 +584,7 @@ export function create(opts) {
 }
 
 // Build a DocumentFragment from `text`, turning bare http(s) URLs into
-// clickable links that open in a new tab. See docs/web-ui/shape.md::Shared
+// clickable links that open in a new tab. See docs/4-implementation/web-ui/shape.md::Shared
 // terminal pane (linkify) for the text-node-only / no-innerHTML
 // XSS-safety + trailing-punctuation strip.
 const LINKIFY_URL_RE = /https?:\/\/[^\s<>"']+/g;

frontend/packages/shared/src/theme.css

@@ -9,7 +9,7 @@
    `@import` and bake the palette into every CSS bundle.
 
    A theme swap touches only `colors.css` (the 16 base16 slots); this
-   derivation layer never changes. See docs/web-ui/css-vars.md. */
+   derivation layer never changes. See docs/4-implementation/web-ui/css-vars.md. */
 :root {
   --bg: var(--base00);
   --bg-elev: var(--base01); /* elevated surfaces: dropdowns, popovers */