docs: restructure into topic subdirectories, collapse duplicated index
Per mara's go-ahead on hyperhive#3902 ("getting started is good, but
terminal rendering does not go in there i think"):
Moved 21 top-level docs/*.md files into 7 new topic subdirectories
(existing web-ui/, turn-loop/, swarm/, tools/, crates/ untouched):
getting-started/ setup.md
agent-lifecycle/ agent-hierarchy.md, approvals.md, persistence.md
trust-boundary/ boundary.md, security.md
integrations/ forge.md, matrix.md, github.md, knowledge.md
networking/ gateway.md, network.md, snapshot-store.md
scheduler/ jobq.md, coordinator.md, ci.md, observability.md
process/ conventions.md, gotchas.md, pr-review-gate.md
web-ui/ terminal-rendering.md (moved into the EXISTING dir,
per mara's correction to the original getting-started
guess -- it's UI implementation detail, not onboarding)
The physical layout now matches docs/README.md's own topical headers,
which already amounted to this taxonomy -- see the scoping comment on
the issue for the two findings that motivated this (a genuine
duplication between CLAUDE.md's old "Reading paths" list and
docs/README.md's grouped one, since drifted out of sync with each
other; and the flat layout not matching the grouping we already had).
Fixed every cross-reference this moved across the whole repo (~120
files: docs/ internal links at every depth, Rust doc comments, nix
module option docs, crate READMEs) -- verified two ways: a grep sweep
confirming zero remaining references to any old path, and a script
that resolves every markdown link in docs/**/*.md + CLAUDE.md +
README.md against the filesystem and reports anything that doesn't
exist (zero broken links).
Collapsed CLAUDE.md's "Reading paths" section (the duplicate) down to
a pointer at docs/README.md, now the single index. Rewrote
docs/README.md itself to use the new subdirectory paths and added the
one doc it was missing that CLAUDE.md's old copy had (pr-review-gate.md).
Classified all 22 docs/*.md files first via a haiku subagent (mara's
suggestion) on two axes -- proposed grouping and operator-vs-
implementation focus -- before finalizing the taxonomy; spot-checked
the report and found internal inconsistencies (its classification
table disagreed with its own summary section for a few files), so this
taxonomy is my original proposal + the one correction mara gave
directly, not a blind application of the subagent's table. The
operator-focus data it gathered is still useful for a follow-up
content pass (docs skewing 'mixed' rather than pure operator-facing),
not addressed in this PR -- structure only.
nix fmt clean, both pre-push lints clean.
This commit is contained in:
iris
mara
parent
e4a22b4190
commit
07b62612b0
124 changed files with 301 additions and 377 deletions
|
|
@ -5,7 +5,7 @@
|
|||
# answers on the hive bridge, so neither can be confined to a network
|
||||
# namespace of its own.
|
||||
# Full vhost map + discovery flow + design rationale in
|
||||
# `docs/gateway.md`. Layout: ./options.nix (option declarations),
|
||||
# `docs/networking/gateway.md`. Layout: ./options.nix (option declarations),
|
||||
# ./vhosts.nix (the nginx virtual-host tree), ./error-pages.nix
|
||||
# (styled static pages), ./dnsmasq.nix (resolver + DHCP config).
|
||||
{
|
||||
|
|
@ -313,7 +313,7 @@ in
|
|||
# from an interrupted oneshot, etc.). The leaf covers the bare
|
||||
# hive domain plus `forge.`, `matrix.` and `*.${hyperhiveDomain}`
|
||||
# so all sub-domains validate under the same cert + the hive CA.
|
||||
# See `docs/gateway.md` ("Self-signed TLS").
|
||||
# See `docs/networking/gateway.md` ("Self-signed TLS").
|
||||
systemd.services.hive-gateway-self-signed-cert = lib.mkIf useSelfSigned {
|
||||
description = "Import host-generated TLS leaf for hive-gateway";
|
||||
wantedBy = [ "multi-user.target" ];
|
||||
|
|
@ -444,7 +444,7 @@ in
|
|||
};
|
||||
|
||||
# `/etc/hosts` entries for local dev — the bare hive domain plus
|
||||
# every name a service module contributed. See `docs/gateway.md`
|
||||
# every name a service module contributed. See `docs/networking/gateway.md`
|
||||
# ("Local dev").
|
||||
#
|
||||
# This used to restate the per-service list a THIRD time (after the
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
# Static error/help pages the gateway serves for routes it has
|
||||
# special-cased, all rendered from one Catppuccin-styled template.
|
||||
# Useful pages instead of nginx's default 404/502 — see
|
||||
# `docs/gateway.md::Per-agent error pages` for the design rationale +
|
||||
# `docs/networking/gateway.md::Per-agent error pages` for the design rationale +
|
||||
# page-vs-status semantics. Consumed by ./vhosts.nix.
|
||||
{ pkgs }:
|
||||
let
|
||||
|
|
|
|||
|
|
@ -53,7 +53,7 @@ in
|
|||
# The gateway always terminates TLS: self-signed is the implicit
|
||||
# floor when neither `tls.certDir` nor ACME is set, so there is no
|
||||
# http-only mode. Listen addresses every vhost shares — plain http
|
||||
# on `cfg.port` plus TLS on `cfg.httpsPort`. See `docs/gateway.md`
|
||||
# on `cfg.port` plus TLS on `cfg.httpsPort`. See `docs/networking/gateway.md`
|
||||
# ("TLS modes").
|
||||
listen = [
|
||||
{
|
||||
|
|
@ -92,7 +92,7 @@ in
|
|||
# — invisibly, it works and keeps working against any certificate at
|
||||
# all. Full reasoning for every directive here (plus two real
|
||||
# footguns — session-cache keying, and a `Host`-header clobber that
|
||||
# can recurse a subrequest into itself) is in docs/gateway.md's
|
||||
# can recurse a subrequest into itself) is in docs/networking/gateway.md's
|
||||
# "Dialing another vhost by name" section — read it before touching
|
||||
# this.
|
||||
verifiedProxyTo = name: ''
|
||||
|
|
|
|||
|
|
@ -36,13 +36,13 @@ let
|
|||
# mints into responses (well-known JSON, the deprecated
|
||||
# `<hive>/matrix/*` 301 redirect, future absolute-URL needs):
|
||||
# always `https://<host>` (matrix-spec compliance) — the canonical
|
||||
# 443 elides the port. See `docs/gateway.md` ("Self-signed TLS").
|
||||
# 443 elides the port. See `docs/networking/gateway.md` ("Self-signed TLS").
|
||||
publicScheme = "https";
|
||||
publicPort = cfg.httpsPort;
|
||||
publicPortSuffix = if publicPort == 443 then "" else ":${toString publicPort}";
|
||||
|
||||
# `<hive>/matrix/*` → 301 → `matrix.<hive>/$1` (legacy deep-link
|
||||
# shim during the fluffychat sub-domain move). See `docs/gateway.md`.
|
||||
# shim during the fluffychat sub-domain move). See `docs/networking/gateway.md`.
|
||||
matrixRedirectLocations =
|
||||
lib.optionalAttrs (matrixCfg.enable && matrixCfg.gui.enable && matrixCfg.gatewayHost != null)
|
||||
(
|
||||
|
|
@ -61,7 +61,7 @@ let
|
|||
# `.well-known/matrix/{client,server}` discovery JSON. Points
|
||||
# clients at `matrixCfg.gatewayHost` when set; falls back to direct
|
||||
# `<hive>:<httpPort>`. CORS `*` per matrix spec. The `m.server`
|
||||
# port-8448 carve-out is documented inline. See `docs/gateway.md`.
|
||||
# port-8448 carve-out is documented inline. See `docs/networking/gateway.md`.
|
||||
wellKnownLocations = lib.optionalAttrs matrixCfg.enable (
|
||||
let
|
||||
clientBaseUrl =
|
||||
|
|
@ -77,7 +77,7 @@ let
|
|||
# (which drops :443) is right for the client base_url above but
|
||||
# wrong for federation delegation. Without this, peers federate to
|
||||
# <gatewayHost>:8448 (closed) while the endpoint actually lives on
|
||||
# the gateway's 443 vhost. See docs/gateway.md discovery flow.
|
||||
# the gateway's 443 vhost. See docs/networking/gateway.md discovery flow.
|
||||
serverHostPort =
|
||||
if matrixCfg.gatewayHost != null then
|
||||
"${matrixCfg.gatewayHost}:${toString publicPort}"
|
||||
|
|
|
|||
Loading…
Reference in a new issue