docs: add agent configuration section to README (supersedes #302)

README.md

@@ -78,6 +78,34 @@ manager container, and auto-rebuilds any container whose hyperhive
 rev goes stale. `claude-code` is unfree — hyperhive scopes the
 whitelist to itself, nothing for the operator to set.
 
+## Agent configuration
+
+Per-agent settings live in each agent's `agent.nix` and are synced to
+the container as environment variables. Common options:
+
+- **`hyperhive.model`** — Claude model for this agent (default: `"haiku"`).
+  Sets `HIVE_DEFAULT_MODEL` in the container; the operator can override
+  at runtime via the per-agent web UI (persisted to state dir).
+- **`hyperhive.allowedRecipients`** — List of agent names this agent can
+  message (via `send`). If unset, all agents are allowed. Useful to
+  restrict an agent to talking only to the manager.
+- **`hyperhive.forge.url`** — Base URL of the hyperhive-managed Forgejo
+  (default: `"http://localhost:3000"`). Used to configure the agent's
+  tea login at boot; no-op if `/state/forge-token` is missing.
+- **`hyperhive.forge.keepSubscriptions`** — Boolean. If `true`, the agent's
+  forge repo subscriptions are never auto-cleaned during rebuild; useful
+  for agents that want to watch specific repos. Rendered as
+  `HIVE_FORGE_KEEP_SUBSCRIPTIONS`.
+- **`hyperhive.forge.skipNotifyReasons`** — List of forge notification
+  `reason` values to suppress (e.g. `[ "subscribed" "participating" ]`).
+  Notifications matching these reasons are silently dropped; all others
+  including direct mentions and reviews are delivered. Empty list (default)
+  delivers all notifications. Rendered as `HIVE_FORGE_NOTIFY_SKIP_REASONS`
+  (comma-separated).
+
+See `nix/templates/harness-base.nix` for the full list of options and
+their descriptions.
+
 ## Build / deploy
 
 ```sh