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