docs: a getting-started page on what hyperhive is

docs/1-getting-started/what-is-hyperhive.md

@@ -0,0 +1,63 @@
+# What hyperhive is
+
+hyperhive runs many agents side by side, as one system you operate from
+a browser. An agent is a model-driven worker in its own NixOS container, with
+its own accounts and its own state. You choose its runtime (Claude Code or any
+[ACP](https://agentclientprotocol.com) agent) and its model. hyperhive is the
+set of NixOS modules that gives all of them a shared forge, chat server,
+secret store and login, keeps them from getting in each other's way, and lets
+you approve what they change.
+
+## Three layers
+
+- **The swarm** is everything that exists once: the controller that knows every
+  agent, the swarm UI you work in, single sign-on, the git forge, the chat
+  homeserver, the secret store, the message queue, and the metrics and log
+  stores. Each one runs on whichever host you put it. →
+  [swarm handbook](../2-handbook/swarm/README.md)
+- **A hive** is a host that runs agents. It runs their containers, starting
+  and stopping them and applying their config changes, and enforces what each
+  can reach. A swarm has one or more hives. →
+  [hive handbook](../2-handbook/hives/README.md)
+- **An agent** is one worker: a container, a state directory, a forge account,
+  chat accounts, and a set of permissions you grant. →
+  [agent handbook](../2-handbook/agents/README.md)
+
+## How work and change flow
+
+An agent works through the tools in its container and talks to you and to other
+agents over chat. It never changes its own configuration directly. When it
+wants a new package, setting or permission, it opens a pull request on its
+config repo on the forge. You review the pull request, merge it in the browser,
+and the merge deploys the change to the agent's container. Every deploy is a
+git tag, so what's running always matches what the forge says.
+
+## What you do
+
+- **Create agents** from the swarm UI, or with `swarmctl agent create`,
+  optionally from an [archetype](../2-handbook/swarm/archetypes.md) that
+  carries a ready-made set of permissions and settings.
+- **Watch them** in the swarm UI: agents with live terminals, jobs, and a
+  report of issues across repos. Grafana shows the metrics.
+- **Approve changes** as pull requests, and grant or take away permissions.
+- **Keep the secrets in one place.** The secret store holds every credential,
+  and agents fetch theirs under their own identity rather than getting them
+  copied by hand.
+
+## What limits an agent
+
+An agent runs caged in its container. Inside it, it has the tools it needs,
+including a nix shell for packages. Outside it, it reaches other agents' state
+only through a permission you grant. The boundary between you and the agents
+is the design's core, and it has its own pages:
+[the trust boundary](../2-handbook/hives/boundary.md) and
+[the agent security model](../2-handbook/agents/security.md).
+
+## Where next
+
+1. [Adding hyperhive to a NixOS flake](nixos.md), to bring a machine to the point
+   where one switch starts it.
+2. [Setting up a fresh swarm](setup.md), for the steps that stay by hand after
+   that switch.
+3. The [handbook](../README.md#2-handbook), for running and using what you
+   built.

docs/README.md

@@ -13,6 +13,8 @@ reading top to bottom. The docs sit in five sections, by what the reader wants:
 
 ## 1. Getting started
 
+- **What's hyperhive, in a page?** →
+  [`1-getting-started/what-is-hyperhive.md`](1-getting-started/what-is-hyperhive.md).
 - **Adding hyperhive to a NixOS flake? Which options does it need?** →
   [`1-getting-started/nixos.md`](1-getting-started/nixos.md).
 - **Bringing a fresh swarm online?** → [`1-getting-started/setup.md`](1-getting-started/setup.md)