docs: scrub #NNN self-references (closes #719)

Last pass of the docs-from-code → docs/ epic (#708). Drops every
attribution cookie from docs/ + README.md + CLAUDE.md so the
source-tree files no longer reference the issue tracker. Issue
threads + commit history retain the references — those are the
canonical record.

- README.md: drop #701 / #660×2 / #551 from matrix + display-name
  sections, rephrase to convey the semantics directly
- CLAUDE.md: scrub 18 cookies from the file map (#655, #15, #784,
  #832, #444, #425, #361, #548, #598, #539, #544, #589, #701,
  #658, #280, #660, #551, #764, #772, #793, #14, #805)
- docs/agent-hierarchy.md: drop #658 ×3 (per-agent user is the
  current shape, not a transition)
- docs/conventions.md: drop #571 (replaced with a docs xref to
  persistence.md::matrix-avatar-sync)
- docs/gateway.md: scrub vhost-map table cookies + Sub-domain
  rationale + Per-agent unix-socket upstream + Self-signed TLS +
  Firewall posture + HIVE_FORGE_URL + Per-agent error pages
  sections; drop the trailing 'Sequencing history' issue list +
  the 'Next-up' issue-link footnote
- docs/matrix.md: scrub serverName/gatewayHost + Default-closed
  firewall + Provisioning flow + Initial rollout + Assertion
  rationale + fluffychat-web build fixes; drop the trailing
  'Sequencing history' issue list
- docs/network.md: drop 'Why ship before #14' #805 quote +
  Container shape #805 attribution + trailing 'Sequencing history'
  + Cross-references issue links; rename v2 column to 'after netns
  isolation'
- docs/web-ui.md: drop #784 from Container row, replace with a
  docs xref to docs/gateway.md::Per-agent unix-socket upstream

Only remaining #NNN in docs/ is the literal markdown-heading
example in docs/forge.md (`#tag`, `#123`, `#!/bin/bash`)
which demonstrates the renderer's behaviour — not an attribution
cookie.
This commit is contained in:
iris 2026-05-31 17:47:21 +02:00
commit 6bdfe52386
8 changed files with 142 additions and 187 deletions

View file

@ -1,23 +1,21 @@
# hive-network
Host-side bridge + per-agent DNS resolver — the foundation that
makes [`#14` container netns isolation](http://localhost:3000/hyperhive/hyperhive/issues/14)
safe to land. Configured via `services.hyperhive.network.*`; off by
default during rollout.
makes container netns isolation safe to land. Configured via
`services.hyperhive.network.*`; off by default during rollout.
## Why ship before #14
## Why ship before netns isolation
Mara on #805#issuecomment-11541: "we need it before #14 so nothing
breaks when we switch over". If netns isolation lands first, agent
containers lose `/etc/resolv.conf` propagation from the host and DNS
breaks until a separate resolver is up. Inverting the sequence —
bridge + dnsmasq first, netns flip second — makes the flag day
boring: the resolver endpoint is already live, agents just discover
it via veth instead of shared netns.
If netns isolation lands first, agent containers lose
`/etc/resolv.conf` propagation from the host and DNS breaks until a
separate resolver is up. Inverting the sequence — bridge + dnsmasq
first, netns flip second — makes the flag day boring: the resolver
endpoint is already live, agents just discover it via veth instead
of shared netns.
## v1 vs v2
| feature | v1 (this PR) | v2 (after #14) |
| feature | v1 (this PR) | v2 (after netns isolation) |
|---|---|---|
| bridge interface | created on host, no slave NICs | per-agent veth pairs attach |
| dnsmasq binding | bridge IP (reachable via host loopback in shared netns) | bridge IP (reachable via veth in private netns) |
@ -27,18 +25,17 @@ it via veth instead of shared netns.
The `address` rules ship pointing at the bridge IP from v1 so the
DNS contract is fixed before any container actually depends on it
— minimises the things that flip on #14 day.
— minimises the things that flip on netns day.
## Container shape (where dnsmasq lives)
Co-located in the existing `hive-gateway` container per mara on
#805:10957 — single front-door for both DNS and HTTP, saves a
sibling container, single systemd-unit / state surface to monitor.
The gateway shares host netns (`privateNetwork = false`) so
dnsmasq's `bind-interfaces` listener on `bridgeIp` works without
any veth gymnastics today; when #14 flips agent containers to
private netns the binding doesn't change (it's still on the host's
bridge interface).
Co-located in the existing `hive-gateway` container — single
front-door for both DNS and HTTP, saves a sibling container, single
systemd-unit / state surface to monitor. The gateway shares host
netns (`privateNetwork = false`) so dnsmasq's `bind-interfaces`
listener on `bridgeIp` works without any veth gymnastics today; when
agent containers flip to private netns the binding doesn't change
(it's still on the host's bridge interface).
## Configuration
@ -98,16 +95,6 @@ agent containers.
interface only. Other interfaces stay closed. The hive resolver
isn't an external-facing service.
## Sequencing history
- mara on #805 (`comment-10957`): "can we put the resolver into the
gateway container?" — yes, this v1 does that.
- mara on #805 (`comment-11541`): "we need it before #14 so nothing
breaks when we switch over" — flipped the dependency direction;
v1 ships now, #14 flips containers later.
## Cross-references
- Issue [#805](http://localhost:3000/hyperhive/hyperhive/issues/805) — DNS resolver tracking
- Issue [#14](http://localhost:3000/hyperhive/hyperhive/issues/14) — netns isolation (downstream consumer)
- `docs/gateway.md` — vhost map + the gateway container's other duties