From caf5896303d4945178ef61f11ee8a8ebdc485b80 Mon Sep 17 00:00:00 2001
From: atlas <atlas@hyperhive.local>
Date: Wed, 2 Sep 2026 02:16:35 +0200
Subject: [PATCH] docs: repoint every reference the docs/ reorg left dangling
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`docs/` was reorganised into topic subdirectories and the references to it
were not moved with it. Thirteen distinct paths and three relative links no
longer resolved, spread across nix, css, html, js, markdown and
.prettierignore — a stale pointer is not a markdown problem, it is wherever
someone wrote a path down.

Each mapping resolved to exactly one target. `docs/matrix.md` was the sole
ambiguous basename: .prettierignore lists `docs/tools/matrix.md` separately
and that entry still resolves, so the stale one is the integrations doc.

The three relative links were each one `../` too deep — from `<crate>/src/`
two levels reach the repo root. `hive-agent/src/login.rs` already had the
correct form, in the same crate, at the same depth.

.prettierignore is repointed rather than dropped, though nothing in the tree
runs prettier: no treefmt entry, no CI job, no package script. Whether that
config should exist at all is a separate question from whether it names
files that do.
---
 .prettierignore                                    | 12 ++++++------
 docs/agent-lifecycle/approvals.md                  |  4 ++--
 docs/agent-lifecycle/persistence.md                |  2 +-
 docs/networking/network.md                         |  4 ++--
 docs/networking/snapshot-store.md                  |  2 +-
 docs/process/conventions.md                        |  8 ++++----
 docs/process/gotchas.md                            |  4 ++--
 docs/scheduler/ci.md                               |  4 ++--
 docs/scheduler/coordinator.md                      | 12 ++++++------
 docs/scheduler/observability.md                    |  4 ++--
 docs/trust-boundary/boundary.md                    |  6 +++---
 frontend/packages/dashboard/src/core.html          |  2 +-
 frontend/packages/dashboard/src/swarm.js           |  2 +-
 frontend/packages/shared/src/terminal/terminal.css |  4 ++--
 nix/host-modules/swarm-otel.nix                    |  2 +-
 15 files changed, 36 insertions(+), 36 deletions(-)

diff --git a/.prettierignore b/.prettierignore
index 8c27f02e..35f58a1f 100644
--- a/.prettierignore
+++ b/.prettierignore
@@ -8,12 +8,12 @@ docs/tools/hivectl-cli.md
 # indentation normalisation, so these files need manual re-wrap before
 # adding them back to the formatter scope.
 CLAUDE.md
-docs/approvals.md
-docs/conventions.md
-docs/gateway.md
-docs/matrix.md
-docs/persistence.md
-docs/terminal-rendering.md
+docs/agent-lifecycle/approvals.md
+docs/process/conventions.md
+docs/networking/gateway.md
+docs/integrations/matrix.md
+docs/agent-lifecycle/persistence.md
+docs/web-ui/terminal-rendering.md
 docs/tools/forge.md
 docs/tools/matrix.md
 docs/turn-loop/README.md
diff --git a/docs/agent-lifecycle/approvals.md b/docs/agent-lifecycle/approvals.md
index 5ed06c2c..cb44e3ce 100644
--- a/docs/agent-lifecycle/approvals.md
+++ b/docs/agent-lifecycle/approvals.md
@@ -209,7 +209,7 @@ One-shot rows fire once (if past due, on the next worker pass) and are deleted b
 ### Scheduled prompt delivery: todo, not a broker message
 
 An agent target's delivery is `push_todo` (`Coordinator::push_todo`,
-`docs/coordinator.md` covers the mechanism generally), not a broker
+`docs/scheduler/coordinator.md` covers the mechanism generally), not a broker
 `Message` — a scheduled prompt wakes its target with a todo instead of
 driving an immediate turn, by design. `key = "schedule:<id>"` per
 target drives `push_todo`'s own upsert-by-key dedup: a re-fire of the
@@ -419,7 +419,7 @@ submitter pushes again (or closes it) to retry.
 
 Long-running approval work — `MergeConfigPr`, `UpdateMetaInputs`,
 `Spawn` — runs as a DAG on the global job queue
-(`docs/coordinator.md::Job queue`), submitted by the approval handler
+(`docs/scheduler/coordinator.md::Job queue`), submitted by the approval handler
 rather than run inline:
 
 | `ApprovalKind` | DAG submitted | source |
diff --git a/docs/agent-lifecycle/persistence.md b/docs/agent-lifecycle/persistence.md
index 04bf7672..5bb14834 100644
--- a/docs/agent-lifecycle/persistence.md
+++ b/docs/agent-lifecycle/persistence.md
@@ -466,7 +466,7 @@ subvolume creation/deletion above.
 
 This is the same subvolume `hivectl agent <name> subvol snapshot push`
 sends to the swarm's snapshot store — see
-[`docs/snapshot-store.md`](../networking/snapshot-store.md) for what a pushed
+[`docs/networking/snapshot-store.md`](../networking/snapshot-store.md) for what a pushed
 snapshot contains and how the store authenticates a sender.
 
 ## `/var/lib/swarm-controller/` (swarm-controller host only)
diff --git a/docs/networking/network.md b/docs/networking/network.md
index c6b34978..653e264b 100644
--- a/docs/networking/network.md
+++ b/docs/networking/network.md
@@ -184,7 +184,7 @@ host-side service on another port — e.g. a dev OTLP collector you want
 agents to reach directly — is unreachable. (hyperhive's own telemetry
 needs none of this: `otel.enable` opens its collector's port itself, and
 `otel.endpoint` is the *upstream*, which no agent ever dials. See
-`docs/observability.md`.)
+`docs/scheduler/observability.md`.)
 
 `services.hyperhive.network.exposeHostPorts = [ 4318 ];` opens each
 listed TCP port `P` on the bridge-interface `allowedTCPPorts`, so an
@@ -274,4 +274,4 @@ loopback — the hive-c0re admin socket is a UDS, not TCP.
 
 ## Cross-references
 
-- `docs/gateway.md` — vhost map + the gateway's other duties
+- `docs/networking/gateway.md` — vhost map + the gateway's other duties
diff --git a/docs/networking/snapshot-store.md b/docs/networking/snapshot-store.md
index d3c3e2a6..f15d6e55 100644
--- a/docs/networking/snapshot-store.md
+++ b/docs/networking/snapshot-store.md
@@ -184,7 +184,7 @@ the access-review list.
 
 The snapshot covers an agent's **state subvolume**, which is the parent
 of `state/`, `claude/` and `harness/` (see
-[`docs/persistence.md`'s btrfs subvolume
+[`docs/agent-lifecycle/persistence.md`'s btrfs subvolume
 section](../agent-lifecycle/persistence.md#btrfs-subvolumes-for-varlibhyperhiveagentsname)
 for how and when that subvolume is created). Consequences:
 
diff --git a/docs/process/conventions.md b/docs/process/conventions.md
index 3282cffd..2a456c53 100644
--- a/docs/process/conventions.md
+++ b/docs/process/conventions.md
@@ -195,7 +195,7 @@ Per-variant fields:
   — `agent` is the affected agent (target of the spawn / config
   commit), not the asker. `description` is the manager's free-text
   blurb shown on the dashboard card. `commit_ref` is the
-  kind-specific payload (see `docs/approvals.md::Approval kinds
+  kind-specific payload (see `docs/agent-lifecycle/approvals.md::Approval kinds
   (wire shapes)`).
 - `Reminder { id, owner, message, due_at, age_seconds }` —
   `due_at` is the absolute time the scheduler is targeting (RFC
@@ -424,7 +424,7 @@ start runs across the `StopForUpdate → Swap → RebuildBookkeeping`
 brace and the tail `Reconcile` node. `flake.nix` itself is no longer
 regenerated host-side on rebuild — it's tracked in the agent's
 proposed/applied repos and rides along on every fetch (see
-`docs/approvals.md::Two repos per agent`).
+`docs/agent-lifecycle/approvals.md::Two repos per agent`).
 
 Anything that changes per-container state on the host should be
 re-applied here so a manual `↻ R3BU1LD` from the dashboard is
@@ -528,7 +528,7 @@ the state dir at provisioning time:
 
 (The matrix profile avatar is **not** a oneshot — `hive-matrix-daemon`
 sets it over its live authenticated Client; see
-`docs/persistence.md::matrix avatar`.)
+`docs/agent-lifecycle/persistence.md::matrix avatar`.)
 
 Shape contract — every one of these:
 
@@ -549,7 +549,7 @@ Shape contract — every one of these:
 5. **Re-runnable**: a second invocation produces the same final
    state (idempotent uploads, idempotent config rewrites). Used
    by the `.path` watchers that re-fire on token appearance (see
-   `docs/persistence.md::Matrix per-agent daemon`).
+   `docs/agent-lifecycle/persistence.md::Matrix per-agent daemon`).
 
 The artefact lives under the agent user's home where applicable
 (`~/.config/tea/config.yml`) and is chown'd to that user, but the
diff --git a/docs/process/gotchas.md b/docs/process/gotchas.md
index 50638da7..0182a9f3 100644
--- a/docs/process/gotchas.md
+++ b/docs/process/gotchas.md
@@ -289,7 +289,7 @@ and fail outright if the host daemon's
 `nix.settings.sandbox-fallback` is `false` (nixpkgs default).
 `nix/agent-modules/default.nix` does `lib.mkForce true` so builds
 fall back to unsandboxed local builds rather than failing. Security
-implications: `docs/security.md`.
+implications: `docs/trust-boundary/security.md`.
 
 ### Linking workspace binaries locally needs `nix develop`
 
@@ -377,7 +377,7 @@ connects to the compositor at `127.0.0.1:<vnc_port>`.
 - **Port allocation**: a **fixed** port (`hyperhive.gui.vncPort`,
   default 5900). No per-agent hashing: network isolation is
   unconditional (each agent has its own netns — see
-  `docs/network.md#container-isolation`), so the VNC port is
+  `docs/networking/network.md#container-isolation`), so the VNC port is
   container-local and can't collide across agents. The harness learns
   the port from the `HIVE_GUI_VNC_PORT` env var (set on the harness
   service when `gui.enable`) — no marker file, no runtime hash. (Unlike
diff --git a/docs/scheduler/ci.md b/docs/scheduler/ci.md
index 7c85b73c..86ecacd3 100644
--- a/docs/scheduler/ci.md
+++ b/docs/scheduler/ci.md
@@ -102,7 +102,7 @@ build can't hold the runner's single slot indefinitely).
 
 - **Private netns, bridge-attached**: the container runs in its own network namespace (`privateNetwork = true`, `hostBridge`) and reaches hive-forge through the gateway at `http://<forge.domain>` (resolved to the bridge IP via `networking.extraHosts`). It cannot reach host-loopback services — the core dashboard at `127.0.0.1:7000` and the raw forge port are unreachable from CI. Requires `forge.behindGateway = true`.
 - **Non-ephemeral**: runner credentials persist across restarts (written to container's stateDir on first registration, reused thereafter).
-- **Sandbox fallback**: nspawn containers can't create user-namespaces, so nix's sandboxing would always fail. Module sets `nix.settings.sandbox-fallback = true` in the container — nix builds run unsandboxed (safe because the container is already isolated). See `docs/gotchas.md`.
+- **Sandbox fallback**: nspawn containers can't create user-namespaces, so nix's sandboxing would always fail. Module sets `nix.settings.sandbox-fallback = true` in the container — nix builds run unsandboxed (safe because the container is already isolated). See `docs/process/gotchas.md`.
 - **Credential isolation**: the forge admin token (`forge-core-token`) never enters the container. hive-c0re holds it and performs all forge API calls (runner validation + registration-token mint, in `forge/ci_runner.rs`); via hive-priv it writes only the runner registration token to the host env-file `/run/hive-ci/runner-token`, which the container bind-mounts read-only.
 
 ## Auto-registration flow
@@ -235,4 +235,4 @@ GC on the coordinator host won't reclaim space on the builder.
 
 - `nix/host-modules/hive-ci.nix`: runner configuration, auto-registration script, container setup.
 - `.forgejo/workflows/ci.yml`: workflow definition.
-- `docs/gotchas.md`: nix sandboxing limitations in containers.
+- `docs/process/gotchas.md`: nix sandboxing limitations in containers.
diff --git a/docs/scheduler/coordinator.md b/docs/scheduler/coordinator.md
index 8d753aba..fe6dbdda 100644
--- a/docs/scheduler/coordinator.md
+++ b/docs/scheduler/coordinator.md
@@ -1,8 +1,8 @@
 # hive-c0re coordinator internals
 
 Architecture notes for the `hive-c0re` coordinator daemon's internal subsystems.
-For the public API surface (dashboard, socket protocol) see `docs/conventions.md`
-and `docs/persistence.md`.
+For the public API surface (dashboard, socket protocol) see `docs/process/conventions.md`
+and `docs/agent-lifecycle/persistence.md`.
 
 ---
 
@@ -571,7 +571,7 @@ which is almost never desired. Leave off on non-x86 hosts.
 
 ## See also
 
-- `docs/approvals.md` — approval flow + scheduled prompts
-- `docs/persistence.md` — SQLite schema, state-dir layout
-- `docs/conventions.md` — wire protocol, recipient sentinels
-- `docs/agent-hierarchy.md` — topology and parent/child relations
+- `docs/agent-lifecycle/approvals.md` — approval flow + scheduled prompts
+- `docs/agent-lifecycle/persistence.md` — SQLite schema, state-dir layout
+- `docs/process/conventions.md` — wire protocol, recipient sentinels
+- `docs/agent-lifecycle/agent-hierarchy.md` — topology and parent/child relations
diff --git a/docs/scheduler/observability.md b/docs/scheduler/observability.md
index d2e60d23..ff231f10 100644
--- a/docs/scheduler/observability.md
+++ b/docs/scheduler/observability.md
@@ -58,7 +58,7 @@ That is a **different risk from the one the collector fixes**, and strictly
 smaller than what preceded it: before, every agent held the upstream credential
 itself, so it could do all of the above *and* use the token anywhere else. The
 collector removes the token and keeps the pipe. Agents are inside the trust
-boundary (`docs/security.md`: capability = accepted risk), so an agent being
+boundary (`docs/trust-boundary/security.md`: capability = accepted risk), so an agent being
 able to *send* is an accepted extension of that boundary — but it is not
 closed by this design, and nothing here should be read as closing it.
 
@@ -179,7 +179,7 @@ and point whatever consumes it at `10.42.0.1:5432` rather than loopback: inside
 a container, loopback is the *container*. The bridge IP is the host's address on
 the `hive-br0` bridge. The service must also bind an address the bridge can
 reach — a `127.0.0.1`-only listener stays unreachable no matter what the
-firewall allows. See `docs/network.md::Reaching host services` for details.
+firewall allows. See `docs/networking/network.md::Reaching host services` for details.
 
 ⚠️ **None of this is needed for hyperhive's own telemetry** — `otel.enable`
 contributes the collector's port and derives the agent-facing endpoint itself.
diff --git a/docs/trust-boundary/boundary.md b/docs/trust-boundary/boundary.md
index f4ec9fce..3832c001 100644
--- a/docs/trust-boundary/boundary.md
+++ b/docs/trust-boundary/boundary.md
@@ -19,7 +19,7 @@ always on), the gateway proxies all operator-facing traffic, and
   reachable via the gateway.
 - **Agent** — speaks only for itself, only over its per-agent
   unix socket. The socket's identity _is_ the agent (see
-  `docs/conventions.md`, "identity = socket"). An agent must not
+  `docs/process/conventions.md`, "identity = socket"). An agent must not
   be able to reach the core daemon's HTTP surface, another
   agent's socket, or another agent's web UI.
 
@@ -46,7 +46,7 @@ defence-in-depth layered on top.
 
 Network isolation is complete and always on: every agent container
 runs in a private netns behind the hive bridge, and there is no
-shared-netns mode. See `docs/network.md`.
+shared-netns mode. See `docs/networking/network.md`.
 
 Concretely, the core daemon's dashboard `/api` carries **no
 application-layer authentication** — operator-authority routes are served
@@ -125,7 +125,7 @@ nginx reaches all of `/run/hive-agent` as a plain host path. Dropping
 `o=w` removes that permission rather than qualifying it.
 
 ⚠️ **The gateway's nginx and dnsmasq are host services, next to
-`hive-c0re`** (see `docs/gateway.md`) — there is no namespace between
+`hive-c0re`** (see `docs/networking/gateway.md`) — there is no namespace between
 them and the rest of the host. That costs no network isolation: nginx
 binds the host's `:80`/`:443` and reaches `localhost` upstreams, which a
 netns would have to be opened up for anyway.
diff --git a/frontend/packages/dashboard/src/core.html b/frontend/packages/dashboard/src/core.html
index f416a8b8..0c4342bc 100644
--- a/frontend/packages/dashboard/src/core.html
+++ b/frontend/packages/dashboard/src/core.html
@@ -51,7 +51,7 @@
          cgroup v2 on the host. Polled only while this sub-tab is active. -->
     <section class="core-pane" id="core-pane-load" data-tab-pane="load"
              role="tabpanel" aria-labelledby="core-tab-load">
-      <p class="meta">live cpu + memory per agent container, from cgroup v2 on the host. cpu is % of total host capacity (all cores), sampled over ~200ms each refresh; polled every 5s while this tab is open. network is omitted on purpose — agents share the host netns, so there is no per-container counter (see <code>docs/network.md</code>).</p>
+      <p class="meta">live cpu + memory per agent container, from cgroup v2 on the host. cpu is % of total host capacity (all cores), sampled over ~200ms each refresh; polled every 5s while this tab is open. network is omitted on purpose — agents share the host netns, so there is no per-container counter (see <code>docs/networking/network.md</code>).</p>
       <div id="container-load-section">
         <p class="meta">loading…</p>
       </div>
diff --git a/frontend/packages/dashboard/src/swarm.js b/frontend/packages/dashboard/src/swarm.js
index eafefb05..000f69c8 100644
--- a/frontend/packages/dashboard/src/swarm.js
+++ b/frontend/packages/dashboard/src/swarm.js
@@ -619,7 +619,7 @@ export function renderContainers(s) {
   // TCP fallback — the gateway proxies the prefix to the per-agent
   // harness (unix-domain via `agent-sockets.json`, or a computed TCP
   // loopback port while the socket marker is absent). See
-  // `docs/web-ui/dashboard.md::Container row` + `docs/gateway.md::Vhost map`.
+  // `docs/web-ui/dashboard.md::Container row` + `docs/networking/gateway.md::Vhost map`.
   const gatewayLinks = !!(s && s.gateway_enabled);
   // Forge public URL: state.forge_public_url (set by the NixOS module
   // from services.hyperhive.forge.publicUrl) or null — never guessed
diff --git a/frontend/packages/shared/src/terminal/terminal.css b/frontend/packages/shared/src/terminal/terminal.css
index c35f5e12..7f552e19 100644
--- a/frontend/packages/shared/src/terminal/terminal.css
+++ b/frontend/packages/shared/src/terminal/terminal.css
@@ -14,7 +14,7 @@
    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/terminal-rendering.md`. */
+   `docs/web-ui/terminal-rendering.md`. */
 
 .terminal-wrap {
   position: relative;
@@ -106,7 +106,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/terminal-rendering.md. */
+   see docs/web-ui/terminal-rendering.md. */
 .live .level-debug { color: var(--muted); }
 .live .level-info  { color: var(--fg); }
 .live .level-warn  { color: var(--amber); border-left-color: var(--amber); }
diff --git a/nix/host-modules/swarm-otel.nix b/nix/host-modules/swarm-otel.nix
index d1e16055..992811b7 100644
--- a/nix/host-modules/swarm-otel.nix
+++ b/nix/host-modules/swarm-otel.nix
@@ -1,7 +1,7 @@
 # The swarm's telemetry collector: one per swarm, in a `swarm-otel`
 # nixos-container beside the swarm's other shared services. This is the
 # **swarm** tier; `otel.nix` is the hive tier that forwards into it.
-# `docs/observability.md` owns the tier model and why the two stay separate
+# `docs/scheduler/observability.md` owns the tier model and why the two stay separate
 # when co-located.
 #
 # A container rather than a second host unit, for the same reason every