07b62612b0
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.
89 lines
3.7 KiB
Nix
89 lines
3.7 KiB
Nix
# 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/networking/gateway.md::Per-agent error pages` for the design rationale +
|
|
# page-vs-status semantics. Consumed by ./vhosts.nix.
|
|
{ pkgs }:
|
|
let
|
|
mkPage =
|
|
{
|
|
name,
|
|
title,
|
|
accent,
|
|
body,
|
|
}:
|
|
pkgs.writeText "hive-gateway-${name}.html" ''
|
|
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<title>${title} ◆ hyperhive</title>
|
|
<style>
|
|
body { background: #1e1e2e; color: #cdd6f4; font: 14px/1.5 -apple-system, system-ui, sans-serif; margin: 0; padding: 4rem 1rem; text-align: center; }
|
|
h1 { color: ${accent}; font-size: 1.5rem; margin: 0 0 0.5rem; }
|
|
p { max-width: 36rem; margin: 0.5rem auto; color: #a6adc8; }
|
|
code { background: #313244; color: #f5c2e7; padding: 0.1rem 0.35rem; border-radius: 0.2rem; font-size: 0.92em; }
|
|
pre { background: #181825; color: #cdd6f4; text-align: left; display: inline-block; padding: 0.75rem 1.25rem; border-radius: 0.4rem; margin: 0.75rem 0; font-size: 0.88em; line-height: 1.6; }
|
|
a { color: #89b4fa; }
|
|
.hint { color: #a6adc8; font-size: 0.9em; margin-top: 1.5rem; }
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<h1>◆ ${title}</h1>
|
|
${body}
|
|
</body>
|
|
</html>
|
|
'';
|
|
in
|
|
{
|
|
notFound = mkPage {
|
|
name = "agent-not-found";
|
|
title = "agent not found";
|
|
accent = "#cba6f7";
|
|
body = ''
|
|
<p>No agent matches the requested <code>/agent/<name>/</code> path on this hive.</p>
|
|
<p>Operator: check the agent name in <a href="/">the dashboard</a>.</p>
|
|
'';
|
|
};
|
|
|
|
unreachable = mkPage {
|
|
name = "agent-unreachable";
|
|
title = "agent unreachable";
|
|
accent = "#f9e2af";
|
|
body = ''
|
|
<p>The agent's harness web server isn't responding. Container restarting, or the agent crashed.</p>
|
|
<p>Operator: <a href="/">dashboard</a> → check the container status / journal; the page will recover on retry once the harness is back up.</p>
|
|
'';
|
|
};
|
|
|
|
# Shown when the authelia vhost's upstream refuses the connection.
|
|
# Leads with the bootstrap because that is overwhelmingly the cause:
|
|
# authelia treats an empty user store as a FATAL startup error, so an
|
|
# enabled-but-unbootstrapped swarm crash-loops behind a vhost that is
|
|
# working perfectly, and the raw 502 points at the proxy instead.
|
|
ssoUnavailable = mkPage {
|
|
name = "sso-unavailable";
|
|
title = "sso unavailable";
|
|
accent = "#f9e2af";
|
|
body = ''
|
|
<p>The swarm's identity provider isn't answering. The gateway is fine — nothing is listening behind it.</p>
|
|
<p class="hint">Most likely: <strong>no users exist yet.</strong> Authelia refuses to start with an empty user store, so it never finishes booting. Add the first account on the host running it:</p>
|
|
<pre>swarmctl user add <username> \
|
|
--display-name <Name> --email <addr> --group admins</pre>
|
|
<p class="hint">Otherwise check the container: <code>journalctl -M swarm-authelia -u authelia-swarm</code>. This page recovers on reload once the provider is up.</p>
|
|
'';
|
|
};
|
|
|
|
unauthorized = mkPage {
|
|
name = "unauthorized";
|
|
title = "unauthorized";
|
|
accent = "#f38ba8";
|
|
body = ''
|
|
<p>This hive is protected by HTTP Basic auth. Valid credentials are required.</p>
|
|
<p class="hint">Operator: add a user with <code>hivectl gateway create-user</code>:</p>
|
|
<pre>hivectl gateway create-user \
|
|
<username> --password-stdin</pre>
|
|
<p class="hint">Then reload your browser and enter the credentials when prompted.</p>
|
|
'';
|
|
};
|
|
}
|